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Preface 


This  IBM  Redbook  covers  a  variety  of  topics  relating  to  the  practical  application 
of  IBM  DB2  Content  Manager  OnDemand  (simply  referred  to  as  “OnDemand”) 
for  Multiplatforms  Version  7.1 ,  z/OS  Version  7.1 ,  and  iSeries  Common  Server 
Version  5.2  of  the  OnDemand  product.  Where  necessary,  separate  sections  are 
included  to  cover  variations  between  the  different  platforms. 

This  book  is  not  intended  as  a  comprehensive  guide  for  OnDemand,  as  there  are 
a  number  of  other  sources  already  available  addressing  various  subjects  on 
different  platforms.  The  scope  would  otherwise  be  too  great  to  cover.  Rather,  this 
book  is  intended  to  cover  key  areas  that  are  either  not  well  known  to  the 
OnDemand  community  or  misunderstood.  We  reviewed  all  aspects  of  the 
OnDemand  topics  and  decided  to  provide  information  in  the  following  areas: 

►  Administration 

►  Database  structure 

►  Multiple  instances 

►  Storage  management 

►  Performance 

►  PDF  indexing 

►  ODWEK 

►  Xenos  transforms 

►  User  exits 

►  Did  you  know? 

This  book  provides  helpful,  real-world-based  advice,  hints,  and  tips  for  those 
involved  in  the  design,  installation,  configuration,  system  administration,  and 
tuning  of  an  OnDemand  system.  We  intend  to  step  beyond  the  existing 
OnDemand  documentation  to  provide  insight  into  the  issues  which  may  be 
encountered  in  the  setup  and  use  of  OnDemand. 

The  team  that  wrote  this  redbook 

This  redbook  was  produced  by  a  team  of  specialists  from  around  the  world 
working  at  the  International  Technical  Support  Organization,  San  Jose  Center. 

Wei-Dong  Jackie  Zhu  is  a  Project  Leader  in  Content  Management  for  the 
International  Technical  Support  Organization  at  the  Almaden  Research  Center  in 
San  Jose,  California.  She  has  more  than  10  years  of  software  development 
experience  in  document  search  systems,  image  workflow  processing,  and  digital 
media  distribution.  She  holds  a  Master  of  Science  degree  in  Computer  Science 
from  the  University  of  the  Southern  California. 
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Overview  and  concepts 


In  this  chapter  we  provide  an  overview  of  the  IBM  DB2  Content  Manager 
OnDemand  (OnDemand)  system  and  contains  information  that  can  help  you 
better  understand  how  OnDemand  works. 

We  describe  how  OnDemand  manages  reports  and  index  data,  including 
important  information  about  how  OnDemand,  the  database  manager,  and  the 
storage  manager  work  together  to  index,  load,  and  retrieve  documents.  Also,  we 
provide  a  list  of  the  tasks  that  OnDemand  administrators  typically  perform  to 
manage  an  OnDemand  system. 
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1.1  Overview 


OnDemand  supports  any  organization  that  can  benefit  from  hard  copy  or 
microfiche  replacement  and  instant  access  to  information.  An  OnDemand 
system  can  support  small  office  environment  and  large  enterprise  installations 
with  hundreds  of  system  users.  It  can  dramatically  improve  productivity  and 
customer  service  in  many  businesses  by  providing  fast  access  to  information 
stored  in  the  system. 

OnDemand  processes  the  print  output  of  application  programs,  extracts  index 
fields  from  the  data,  stores  the  index  information  in  a  relational  database,  and 
stores  one  or  more  copies  of  the  data  in  the  system.  With  OnDemand,  you  can 
archive  newly  created  and  frequently  accessed  reports  on  high  speed,  disk 
storage  volumes  and  automatically  migrate  them  to  other  types  of  storage 
volumes  as  they  age. 

OnDemand  fully  integrates  the  capabilities  of  Advanced  Function  Presentation 
(AFP™),  including  management  of  resources,  indexes,  and  annotations,  and 
supports  full  fidelity  reprinting  and  faxing  of  documents  to  devices  attached  to  a 
PC,  OnDemand  server,  or  other  server  on  the  network. 

OnDemand  provides  administrators  with  tools  to  manage  OnDemand  servers, 
authorize  users  to  access  OnDemand  servers  and  data  stored  in  the  system,  and 
backup  the  database  and  data  storage. 

OnDemand  provides  users  the  ability  to  view  documents,  print,  send,  and  fax 
copies  of  documents,  and  attach  electronic  notes  to  documents. 

OnDemand  offers  several  advantages;  it  can: 

►  Easily  locate  data  without  specifying  the  exact  report. 

►  Retrieve  the  pages  of  the  report  that  you  need  without  processing  the  entire 
report. 

►  View  selected  data  from  within  a  report. 

OnDemand  can  provide  you  with  an  information  management  tool  that  can 
increase  your  effectiveness  when  working  with  customers. 

OnDemand  does  the  following: 

►  Integrates  data  created  by  application  programs  into  an  online,  electronic 
information  archive  and  retrieval  system. 

►  Provides  controlled  and  reliable  access  to  all  reports  of  an  organization. 

►  Retrieves  data  that  you  need  when  you  need  it. 
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►  Provides  a  standard,  intuitive  client  with  features  such  as  thumbnails, 
bookmarks,  notes,  and  shortcuts. 

These  features  mean  that  OnDemand  can  help  you  quickly  retrieve  the  specific 
page  of  a  report  that  you  need  to  provide  fast  customer  service. 

An  OnDemand  system  consists  of  client  programs  and  server  programs  that 
communicate  over  a  network  running  the  TCP/IP  communications  protocol,  a 
database  manager  that  maintains  index  data  and  server  control  information,  and 
storage  managers  that  maintain  documents  on  various  types  of  storage  devices. 
Figure  1-1  shows  an  example. 


Figure  1-1  OnDemand  system  overview 

OnDemand  client  programs  run  on  PCs  and  terminals  attached  to  the  network 
and  communicate  with  the  OnDemand  servers.  The  OnDemand  library  server 
manages  a  database  of  information  about  the  users  of  the  system  and  the 
reports  stored  on  the  system.  The  OnDemand  object  server  manages  the  reports 
on  disk,  optical,  and  tape  storage  devices.  An  OnDemand  system  has  one  library 
server  and  one  or  more  object  servers.  An  object  server  can  operate  on  the 
same  server  or  node  as  the  library  server,  or  on  a  different  server  or  node  than 
the  library  server. 

OnDemand  client  programs  operate  on  personal  computers  running  on 
Windows.  Using  the  client  program,  users  can  search  for  and  retrieve  reports 
stored  on  the  system.  Specifically,  users  can  construct  queries  and  search  for 
reports,  retrieve  documents  from  OnDemand,  view,  print,  and  fax  copies  or 
pages  of  documents,  and  attach  electronic  notes  to  pages  of  a  document. 
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OnDemand  servers  manage  control  information  and  index  data,  store  and 
retrieve  documents  and  resource  group  files,  and  process  query  requests  from 
OnDemand  client  programs.  The  documents  can  reside  on  disk,  optical,  and  tape 
storage  volumes.  New  reports  can  be  loaded  into  OnDemand  every  day.  This 
way,  OnDemand  can  retrieve  the  latest  information  generated  by  application 
programs. 

OnDemand  client  programs  and  servers  communicate  over  a  computer  network 
supported  by  TCP/IP.  When  a  user  submits  a  query,  the  client  program  sends  a 
search  request  to  the  OnDemand  library  server.  The  library  server  returns  a  list 
of  the  documents  that  match  the  query  to  the  user.  When  the  user  selects  a 
document  for  viewing,  the  client  program  retrieves  a  copy  of  the  document  from 
the  object  server  where  the  document  is  stored,  opens  a  viewing  window,  and 
displays  the  document. 


1.2  Concepts 

The  terms  application ,  application  group ,  and  folder  represent  how  OnDemand 
stores,  manages,  retrieves,  views,  and  prints  reports  and  index  data.  When 
defining  a  new  report  or  type  of  data  to  OnDemand,  an  administrator  must  create 
an  application  and  assign  the  application  to  an  application  group. 


Note:  If  an  application  group  does  not  exist,  the  administrator  must  first  create 
one. 


Before  users  can  search  for  and  retrieve  documents,  an  administrator  must 
create  or  update  a  folder  to  use  the  application  group  and  application. 

Application 

An  application  describes  the  physical  characteristics  of  a  report  to  OnDemand. 
Typically  you  define  an  application  for  each  program  that  produces  output  to  be 
stored  in  OnDemand.  The  application  includes  information  about  the  format  of 
the  data,  the  orientation  of  data  on  the  page,  the  paper  size,  the  record  length, 
and  the  code  page  of  the  data.  The  application  also  includes  parameters  that  the 
indexing  program  uses  to  locate  and  extract  index  data  and  processing 
instructions  that  OnDemand  uses  to  load  index  data  in  the  database  and 
documents  on  storage  volumes. 
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Application  group 

An  application  group  contains  the  storage  management  attributes  of  and  index 
fields  for  the  data  that  you  load  into  OnDemand.  When  you  load  a  report  into 
OnDemand,  you  must  identify  the  application  group  where  OnDemand  will  load 
the  index  data  and  store  the  documents.  An  application  group  is  a  collection  of 
one  or  more  OnDemand  applications  with  common  indexing  and  storage 
management  attributes.  You  typically  group  several  different  reports  in  an 
application  group  so  that  users  can  access  the  information  contained  in  the 
reports  with  a  single  query.  All  of  the  applications  in  the  application  group  must 
be  indexed  on  at  least  one  of  the  same  fields,  for  example,  customer  name, 
account  number,  and  date. 

Folder 

A  folder  is  the  user’s  way  to  query  and  retrieve  data  stored  in  OnDemand.  A 
folder  provides  users  with  a  convenient  way  to  find  related  information  stored  in 
OnDemand,  regardless  of  the  source  of  the  information  or  how  the  data  was 
prepared.  A  folder  allows  an  administrator  to  set  up  a  common  query  screen  for 
several  application  groups  that  may  use  different  indexing  schemes,  so  that  a 
user  can  retrieve  the  data  with  a  single  query.  For  example,  a  folder  called 
Student  Information  might  contain  transcripts,  bills,  and  grades,  which  represents 
information  stored  in  different  application  groups,  defined  in  different 
applications,  and  created  by  different  programs. 

Figure  1-2  illustrates  the  concepts  described  in  this  section. 

Figure  1  -3  shows  some  examples  for  the  described  concepts. 
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A  folder  is  the  object  with  which  users 
query  and  retrieve  reports.  A  folder  can 
query  more  than  one  application  group, 
provided  the  application  groups  have  the 
same  database  fields. 


The  application  group  is  where  you  define 
the  database,  cache  storage,  and  archive 
storage  requirements  for  reports.  An 
application  group  can  contain  more  than 
one  application,  provided  the  applications 
have  the  same  database  and  storage 
management  attributes. 

Each  application  represents  a  report  that 
you  wanttodefine  to  the  system.  You  must 
assign  an  application  to  an  application 
group. 


Figure  1-2  Folders,  application  groups  and  applications  concepts 
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Name:  Student  Information 
Folder  Fields:  Student  Name.  Student 
Number.  Date,  Document  Type 


Name:  BILLS 

Database  Fields:  name,  number.  bDate 
Life  of  Data:  Two  years 
Document  Storage:  cache,  archive 
Name:  GRADES 

Database  Fields:  name,  number.  gDate 
Life  of  Data:  Two  years 
Document  Storage:  cache,  archive 
Name:  TRANS 

Database  Fields:  name,  number,  tDate 
Life  of  Data:  Two  years 
Document  Storage:  cache,  archive 


Name:  BILLS 
Data  Type:  AFP 
Indexer  AC  IF 

Index  Fields:  name,  number,  bDate 
Name:  GRADES 
Data  Type:  AFP 
Indexer  ACIF 

Index  Fields:  name,  number,  gDate 
Name:  TRANS 
Data  Type:  AFP 
Indexer  ACIF 

Index  Fields:  name,  number,  tDate 


Figure  1-3  Folders,  application  groups  and  applications  examples 


Indexing  methods 

OnDemand  provides  two  methods  of  indexing  data 

►  Document  indexing  is  used  for  reports  that  contain  logical  items  such  as 
policies,  and  statements.  Each  of  the  items  in  a  report  can  be  individually 
indexed  on  values  such  as  account  number,  customer  name,  and  balance. 
OnDemand  supports  up  to  32  index  values  per  item.  With  document  indexing, 
the  user  does  not  necessarily  need  to  know  about  reports  or  report  cycles  to 
retrieve  a  document  from  OnDemand. 
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►  Report  indexing  is  used  for  reports  that  contain  many  pages  of  the  same  kind 
of  data,  such  as  a  transaction  log.  Each  line  in  the  report  usually  identifies  a 
specific  transaction,  and  it  would  not  be  cost  effective  to  index  each  line. 
OnDemand  stores  the  report  as  groups  of  pages  and  indexes  each  group. 
When  reports  include  a  sorted  transaction  value  (for  example,  invoice 
number),  OnDemand  can  index  the  data  on  the  transaction  value.  This  is 
done  by  extracting  the  beginning  and  ending  transaction  values  for  each 
group  of  pages  and  storing  the  values  in  the  database.  This  type  of  indexing 
lets  users  retrieve  a  specific  transaction  value  directly. 

Documents 

OnDemand  documents  represent  indexed  groups  of  pages.  Typically  an 
OnDemand  document  is  a  logical  section  of  a  larger  report,  such  as  an  individual 
customer  statement  within  a  report  of  thousands  of  statements.  An  OnDemand 
document  can  also  represent  a  portion  of  a  larger  report.  For  reports  that  do  not 
contain  logical  groups  of  pages,  such  as  transaction  logs,  OnDemand  can  divide 
the  report  into  groups  of  pages.  The  groups  of  pages  are  individually  indexed  and 
can  be  retrieved  much  more  efficiently  than  the  entire  report.  Documents  are 
usually  identified  by  date,  with  one  or  more  other  fields,  such  as  customer  name, 
customer  number,  or  transaction  number.  A  date  is  optional  but  highly 
recommended.  If  there  is  no  date  field,  the  load  ID  looks  like  51 79-1  -0-1 FAA-0-0 
where  the  0-0  on  the  end  means  no  date  was  used. 

Figure  1-4  illustrates  OnDemand  applications  and  documents.  An  administrator 
could  define  the  BILLS  application  for  a  report  that  contains  logical  items,  such 
as  customer  statements.  The  BILLS  application  uses  the  document  indexing 
method  to  divide  the  report  into  documents.  Each  statement  in  the  report 
becomes  a  document  in  OnDemand.  Users  can  retrieve  a  statement  by 
specifying  the  date  and  any  combination  of  name  and  number. 

An  administrator  could  define  the  TRANS  application  for  a  report  that  contains 
lines  of  sorted  transaction  data.  The  TRANS  application  uses  the  report  indexing 
method  to  divide  the  report  into  documents.  Each  group  of  100  pages  in  the 
report  becomes  a  document  in  OnDemand.  Each  group  is  indexed  using  the  first 
and  last  sorted  transaction  values  that  occur  in  the  group.  Users  can  retrieve  the 
group  of  pages  that  contains  a  specific  transaction  number  by  specifying  the  date 
and  the  transaction  number.  OnDemand  retrieves  the  group  that  contains  the 
value  entered  by  the  user. 
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Figure  1-4  Applications  and  documents 


Servers 

The  OnDemand  server  environment  includes  a  library  server  and  one  or  more 
object  servers  residing  on  one  or  more  nodes  connected  to  a  TCP/IP  network. 

A  library  server  maintains  a  central  database  about  the  reports  stored  in 
OnDemand.  The  database  also  contains  information  about  the  objects  defined  to 
the  system,  such  as  users,  groups,  printers,  application  groups,  applications, 
folders,  and  storage  sets.  The  database  manager  provides  the  database  engine 
and  utilities  to  administer  the  database.  The  library  server  processes  client 
logons,  queries,  and  print  requests  and  updates  to  the  database.  The  major 
functions  that  run  on  the  library  server  are  the  request  manager,  the  database 
manager,  and  the  server  print  manager. 

An  object  server  maintains  documents  on  cache  storage  volumes  and,  optionally, 
works  with  an  archive  storage  manager  to  maintain  documents  on  archive  media, 
such  as  optical  and  tape  storage  libraries.  An  object  server  loads  data,  retrieves 
documents,  and  expires  documents.  The  major  functions  that  run  on  an  object 
server  are  the  cache  storage  manager,  OnDemand  data  loading  and 
maintenance  programs,  and  optionally,  the  archive  storage  manager. 

The  basic  OnDemand  configuration  is  a  library  server  and  an  object  server  on 
the  same  physical  system  or  node.  This  single  library/object  server  configuration 
supports  the  database  functions  and  cache  storage  on  one  system.  You  can  add 
an  archive  storage  manager  to  the  single  library/object  server  configuration,  to 
maintain  documents  on  archive  media. 


Chapter  1 .  Overview  and  concepts  9 


You  can  also  configure  your  OnDemand  system  with  a  library  server  on  one  node 
and  one  or  more  object  servers  on  different  nodes.  This  configuration  is  known 
as  a  distributed  library/object  server  system.  The  distributed  library/object  server 
configuration  supports  caching  of  documents  on  different  servers.  You  can  add 
an  archive  storage  manager  to  one  or  more  of  the  object  servers  to  maintain 
documents  on  archive  media  attached  to  different  servers. 

An  OnDemand  server  environment  contains  several  components: 

►  A  request  manager  that  provides  client,  network,  and  operating  system 
services,  security,  and  accounting.  The  request  manager  resides  on  the 
library  server. 

►  A  database  manager  that  maintains  the  index  data  for  the  reports  that  you 
store  on  the  system.  The  database  manager  is  a  relational  database 
management  product,  such  as  DB2.  The  database  manager  resides  on  the 
library  server. 

►  Database  control  information  about  the  users,  groups,  application  groups, 
applications,  folders,  storage  sets,  and  printers  that  you  define  on  the  system. 
The  control  information  determines  who  can  access  the  system,  the  folders 
that  a  user  can  open,  and  the  application  group  data  that  a  user  can  query 
and  retrieve.  The  database  resides  on  the  library  server. 

►  A  cache  storage  manager  that  maintains  documents  in  cache  storage.  Cache 
storage  is  for  high-speed  access  to  the  most  frequently  used  documents. 

►  An  archive  storage  manager,  which  is  an  optional  part  of  the  system.  The 
archive  storage  manager  is  for  the  long-term  storage  of  one  or  more  copies  of 
documents  on  archive  media,  such  as  optical  and  tape  storage  libraries. 

►  A  download  facility  that  automatically  transfers  spool  files  to  a  server  at  high 
speed.  We  recommend  that  you  use  Download  for  OS/390,  a  licensed  feature 
of  Print  Services  Facility™  (PSF)  for  OS/390.  Download  provides  the 
automatic,  high-speed  download  of  JES  spool  files  from  an  OS/390  system  to 
OnDemand  servers.  The  download  facility  is  not  applicable  to  iSeries. 

►  Data  indexing  and  conversion  programs  that  create  index  data,  collect 
required  resources,  and  optionally  convert  line  data  reports  to  AFP  data. 
OnDemand  provides  several  indexing  programs.  The  AFP  Conversion  and 
Indexing  Facility  (ACIF)  can  be  used  to  index  S/390®  line  data,  ASCII  data, 
and  AFP  files,  collect  resources  required  to  view  the  reports,  and  convert  line 
data  files  to  AFP  data.  The  OS/400  Indexer  can  be  used  to  index  a  variety  of 
data  types  and  is  the  most  common  OnDemand  indexer  for  OS/400  spooled 
files.  The  OnDemand  PDF  Indexer  can  be  used  to  create  index  data  for 
Adobe  Acrobat  PDF  files.  The  OnDemand  Generic  Indexer  can  be  used  to 
create  index  data  for  almost  any  other  type  of  data  such  as  HTML  documents, 
Lotus  WordPro  documents,  TIFF  files. 
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►  Data  loading  programs  that  can  be  set  up  to  automatically  store  report  data 
into  application  groups  and  update  the  database.  The  data  loading  programs 
can  run  on  any  OnDemand  server. 

►  Archived  reports  and  resources. 

►  A  server  print  facility  that  allows  users  to  reprint  a  large  volume  of  documents 
at  high  speed.  OnDemand  uses  Infoprint,  which  must  be  purchased 
separately,  to  manage  the  server  print  devices. 

►  OnDemand  management  programs  to  maintain  the  OnDemand  database  and 
documents  in  cache  storage. 

►  A  system  logging  facility  that  provides  administrators  with  tools  to  monitor 
server  activity  and  respond  to  specific  events  as  they  occur.  The  interface  to 
the  system  logging  facility  is  through  the  system  log  folder  and  the  system  log 
user  exit. 

The  following  sections  provide  additional  information  for: 

►  The  OnDemand  request  manager 

►  The  OnDemand  database  manager 

►  The  OnDemand  storage  manager 

►  Download 

►  Data  indexing  and  loading 

►  OnDemand  management  programs 

Request  manager 

The  request  manager  processes  search  requests  from  OnDemand  client 
programs.  When  a  user  enters  a  query,  the  client  program  sends  a  request  over 
the  network  to  the  request  manager.  The  request  manager  works  with  the 
database  manager  to  compile  a  list  of  the  items  that  match  the  query  and  returns 
the  list  to  the  client  program.  When  the  user  selects  an  item  for  viewing,  the 
request  manager  sends  a  retrieval  request  to  the  cache  storage  manager,  if  the 
document  resides  in  cache  storage,  or  to  the  archive  storage  manager,  if  the 
document  resides  in  archive  storage.  The  storage  manager  retrieves  the 
document  and,  optionally,  the  resources  associated  with  the  item.  The 
OnDemand  client  program  decompresses  and  displays  the  document. 

OnDemand  management  programs  include  utilities  that  maintain  the  database 
and  cache  storage,  including  the  ability  to  automatically  migrate  data  from  the 
database  and  cache  storage  to  archive  storage.  These  programs  use  the 
services  of  the  request  manager  to  manage  index  data,  documents,  and 
resource  files. 
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When  a  user  logs  on  to  the  system,  OnDemand  assigns  a  unique  transaction 
number  to  that  instance  of  the  client  program.  All  activity  associated  with  that 
instance  of  the  client  program  contains  the  same  transaction  number.  The 
request  manager  records  messages  generated  by  the  various  OnDemand 
programs  in  the  system  log,  for  example,  logon,  query,  and  print.  The  messages 
contain  the  transaction  number,  user  ID,  time  stamp,  and  other  information. 
Administrators  can  open  the  system  log  folder  and  view  the  messages. 
OnDemand  also  provides  a  system  log  user  exit  so  that  you  can  run  a 
user-defined  program  to  process  messages.  For  example,  you  could  design  a 
user-defined  program  to  send  an  alert  to  an  administrator  when  certain 
messages  appear  in  the  system  log.  The  messages  in  the  system  log  can  also 
be  used  to  generate  usage  and  billing  reports. 

Database  manager 

OnDemand  uses  a  database  management  product,  such  as  DB2,  to  maintain  the 
index  data  for  the  reports  that  you  load  into  the  system.  The  database  manager 
also  maintains  the  OnDemand  system  tables  that  describe  the  applications, 
application  groups,  storage  sets,  folders,  groups,  users,  and  printers  that  you 
define  to  the  system.  You  should  periodically  collect  statistics  on  the  tables  in  the 
database  to  optimize  the  operation  of  the  OnDemand  database. 

Storage  manager 

The  OnDemand  cache  storage  manager  maintains  a  copy  of  documents,  usually 
temporarily,  on  disk.  The  cache  storage  manager  uses  a  list  of  file  systems  to 
determine  the  devices  available  to  store  and  maintain  documents.  You  typically 
define  a  set  of  cache  storage  devices  on  each  object  server  so  that  the  data 
loaded  on  the  server  can  be  placed  on  the  fastest  devices  to  provide  the  most 
benefit  to  your  users.  For  multiplatforms  and  z/OS,  the  cache  storage  manager 
uses  the  arsmaint  command  to  migrate  documents  from  cache  storage  to 
archive  media  and  to  remove  documents  that  have  passed  their  life  of  data 
period.  For  iSeries,  the  Start  Disk  Storage  Management  (STRDSMOND)  command 
starts  Disk  Storage  Management  (DSM)  task  that  manage  data  from  between 
disk  and  the  Archived  Storage  Manager  (ASM). 

OnDemand  also  supports  an  archive  storage  manager ,  such  as  Tivoli  Storage 
Manager  (TSM)  for  Multiplatforms,  Object  Access  Method  (OAM)  for  z/OS, 
Virtual  Storage  Access  Method  (VSAM)  for  z/OS,  and  Archive  Storage  Manager 
(ASM)  for  iSeries.  The  archive  storage  manager  maintains  one  or  more  copies  of 
documents  on  archive  media,  such  as  optical  or  tape  storage  libraries.  You 
decide  which  types  of  archive  media  that  your  OnDemand  system  must  support, 
configure  the  storage  devices  on  the  system,  and  define  the  storage  devices  to 
the  archive  storage  manager.  To  store  application  group  data  on  archive  media, 
you  must  assign  the  application  group  to  a  storage  set  that  identifies  a  storage 
node  that  is  managed  by  the  archive  storage  manager. 
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Download 

Download  is  a  licensed  feature  of  PSF  for  OS/390.  Download  provides  the 
automatic,  high-speed  download  of  JES  spool  files  from  an  OS/390  system  to  an 
OnDemand  for  Multiplatforms  server.  Download  can  be  used  to  transfer  reports 
created  on  OS/390  systems  to  the  server,  where  you  can  configure  OnDemand 
to  automatically  index  the  reports  and  store  the  reports  and  index  data  on  the 
system.  Download  operates  as  a  JES  Functional  Subsystem  Application  (FSA) 
and  can  automatically  route  jobs  based  on  a  JES  class  or  destination,  reducing 
the  need  to  modify  JCL.  Download  uses  TCP/IP  protocols  to  stream  data  at  high 
speed  over  a  LAN  or  channel  connection  from  an  OS/390  system  to  the 
OnDemand  server. 

Data  indexing  and  loading 

The  reports  that  you  store  in  OnDemand  must  be  indexed.  OnDemand  supports 
several  types  of  index  data  and  indexing  programs.  For  example,  you  can  use 
ACIF  to  extract  index  data  from  the  reports  that  you  want  to  store  on  the  system. 
An  administrator  defines  the  index  fields  and  other  processing  parameters  that 
ACIF  uses  to  locate  and  extract  index  information  from  reports. 

OnDemand  data  loading  programs  read  the  index  data  generated  by  ACIF  and 
load  it  into  the  OnDemand  database.  The  data  loading  programs  obtain  other 
processing  parameters  from  the  OnDemand  database,  such  as  parameters  used 
to  segment,  compress,  and  store  report  data  in  cache  storage  and  on  archive 
media.  If  you  plan  to  index  reports  on  an  OnDemand  server,  you  can  define  the 
parameters  with  the  administrative  client.  The  administrative  client  includes  a 
report  wizard  that  lets  you  create  ACIF  indexing  parameters  by  visually  marking 
up  sample  report  data.  OnDemand  also  provides  indexing  programs  that  can  be 
used  to  generate  index  data  for  Adobe  Acrobat  PDF  files  and  other  types  of 
source  data,  such  as  TIFF  files. 

For  OS/400,  there  is  the  OS/400  Indexer  that  can  index  a  variety  of  data  types  for 
OS/400  spooled  files.  Refer  to  IBM  Content  Manager  OnDemand  for 
Multiplatforms  -  Indexing  Reference,  SC27-0842,  IBM  Content  Manager 
OnDemand  for  iSeries  Common  Server  -  Indexing  Reference,  SC27-1 1 60,  and 
IBM  Content  Manager  OnDemand  for  z/OS  and  OS/390  -  Indexing  Reference, 
SC27-1375  (OnDemand  Indexing  References)  for  details  about  the  indexing 
programs  provided  with  OnDemand  for  various  platforms. 

Figure  1  -5  shows  an  overview  of  the  data  indexing  and  loading  process. 


Chapter  1 .  Overview  and  concepts  1 3 


The  OnDemand  data  loading  program  first  determines  whether  the  report  needs 
to  be  indexed.  If  the  report  needs  to  be  indexed,  the  data  loading  program  calls 
the  appropriate  indexing  program.  The  indexing  program  uses  the  indexing 
parameters  from  the  OnDemand  application  to  process  the  report  data.  The 
indexing  program  can  extract  and  generate  index  data,  divide  the  report  into 
indexed  groups,  and  collect  the  resources  required  to  view  and  reprint  the  report. 

After  indexing  the  report,  the  data  loading  program  processes  the  index  data,  the 
indexed  groups,  and  the  resources  using  other  parameters  from  the  application 
and  application  group.  The  data  loading  program  works  with  the  database 
manager  to  update  the  OnDemand  database  with  index  data  extracted  from  the 
report.  Depending  on  the  storage  management  attributes  of  the  application 
group,  the  data  loading  program  may  work  with  the  cache  storage  manager  to 
segment,  compress,  and  copy  report  data  to  cache  storage  and  the  archive 
storage  manager  to  copy  report  data  to  archive  storage. 
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Management  programs 

OnDemand  provides  programs  to  maintain  and  optimize  the  database  and 
maintain  documents  on  cache  storage.  An  administrator  usually  determines  the 
processing  parameters  for  these  programs,  including  the  frequency  with  which 
the  programs  should  run.  When  you  create  an  application  group,  you  specify 
other  parameters  that  these  programs  use  to  maintain  the  report  data  stored  in 
the  application  group. 

For  example,  when  creating  an  application  group,  the  administrator  specifies  how 
long  documents  should  be  maintained  on  the  system  and  whether  index  data 
should  be  migrated  from  the  database  to  archive  media.  The  programs  use  the 
information  to  migrate  documents  from  cache  storage  to  archive  media,  delete 
documents  from  cache  storage,  migrate  index  data  from  the  database  to  archive 
media,  and  delete  index  data  from  the  database.  These  functions  are  useful 
because  OnDemand  can  reclaim  the  database  and  cache  storage  space 
released  by  expired  and  migrated  data.  We  recommend  that  you  configure  your 
OnDemand  system  to  automatically  start  these  management  programs  on  a 
regular  schedule,  usually  once  every  night  or  week. 

The  archive  storage  manager  deletes  data  from  archive  media  when  it  reaches 
its  storage  expiration  date.  An  administrator  defines  management  information  to 
the  archive  storage  manager  to  support  the  OnDemand  data  it  manages.  The 
management  information  includes  the  storage  libraries  and  storage  volumes  that 
can  contain  OnDemand  data,  the  number  of  copies  of  a  report  to  maintain,  and 
how  long  to  keep  data  in  the  archive  management  system. 

OnDemand  and  the  archive  storage  manager  delete  data  independently  of  each 
other.  Each  uses  its  own  criteria  to  determine  when  to  remove  documents.  Each 
uses  its  own  utilities  and  schedules  to  remove  documents.  However,  for  final 
removal  of  documents  from  the  system,  you  should  specify  the  same  criteria  to 
OnDemand  and  the  archive  storage  manager. 


1.2.1  OnDemand  Web  Enablement  Kit 

The  OnDemand  Web  Enablement  Kit  (ODWEK)  is  an  optional  feature  of 
OnDemand  that  allows  people  to  use  a  Web  browser  to  access  data  stored  in  an 
OnDemand  system.  For  example,  you  can  provide  some  people  with  the  Uniform 
Resource  Locator  (URL)  of  a  Web  page  that  permits  them  to  log  on  to  an 
OnDemand  server;  you  can  provide  other  people  with  the  URL  of  a  Web  page 
that  permits  them  to  search  a  specific  folder.  ODWEK  verifies  that  the  user 
information  is  valid  on  the  OnDemand  server,  such  as  permission  to  access  the 
server  and  data  stored  in  an  application  group.  After  the  user  submits  a  search, 
ODWEK  displays  a  Web  page  that  contains  a  list  of  the  documents  that  match 
the  query.  The  user  selects  a  document  to  view  and  ODWEK  sends  the 
document  to  the  browser. 
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ODWEK  contains  several  components: 

►  The  Web  server  program.  The  server  program  uses  standard  OnDemand 
interfaces  and  protocols  to  access  data  stored  in  an  OnDemand  server.  No 
additional  code  is  needed  on  the  OnDemand  server  to  support  ODWEK.  You 
can  use  one  of  the  following  Web  server  programs  to  control  ODWEK: 

-  CGI  program.  The  CGI  program  runs  against  an  HTTP  server,  such  as  the 
IBM  HTTP  Server. 

-  Java  servlet.  The  servlet  runs  on  a  Java-enabled  HTTP  server  with  a  Java 
application  server,  such  as  the  IBM  WebSphere  Application  Server. 

►  The  AFP  Web  Viewer.  The  AFP  Web  Viewer  lets  users  search,  retrieve,  view, 
navigate,  and  print  AFP  documents  from  a  Web  browser.  The  AFP  Web 
Viewer  must  be  installed  on  the  viewing  workstations. 

►  The  Image  Web  Viewer.  The  Image  Web  Viewer  lets  users  search,  retrieve, 
view,  navigate,  and  print  BMP,  GIF,  JPEG,  PCX,  and  TIFF  documents  from  a 
Web  browser.  The  Image  Web  Viewer  must  be  installed  on  the  viewing 
workstations. 

►  The  Line  Data  Java  applet.  The  Line  Data  applet  lets  users  view  line  data 
documents  from  a  Web  browser. 

►  The  AFP2HTML  Java  applet.  The  AFP2HTML  applet  lets  users  view  the 
output  generated  by  the  IBM  AFP2WEB  Transform  service  offering.  The 
AFP2WEB  Transform  converts  AFP  documents  and  resources  into  HTML 
files  that  can  be  displayed  with  the  AFP2HTML  applet.  If  you  plan  to  use  the 
AFP2HTML  applet,  then  you  must  obtain  the  AFP2WEB  Transform  from  IBM 
and  install  and  configure  it  on  the  Web  server. 

See  Chapter  8,  “Installing  and  customizing  ODWEK”  on  page  1 71 ,  for  a  more 

comprehensive  discussion. 
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Administration 


An  extremely  important  aspect  of  an  OnDemand  system  is  the  effective  design 
and  implementation  of  a  strategy  regarding  system  administration  from  a  report 
administration  perspective  and  from  a  user  authority  and  responsibility 
perspective.  The  focus  of  this  strategy  should  be  to  ensure  that  the  system  is 
planned  in  a  manner  that  provides  the  greatest  functionality  and  the  best 
performance  as  the  system  matures. 

In  this  chapter  we  discuss  the  following  topics: 

►  Report  administration 

►  User  and  group  administration 
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2.1  Report  administration 

Report  design  and  definition  is  a  key  to  a  successful  implementation  of  an 
OnDemand  system.  Knowledge  of  the  data  that  is  to  be  indexed,  loaded,  and 
retrieved,  along  with  knowledge  of  OnDemand  best  practices,  results  in  the  most 
efficient  and  user  friendly  system  possible.  In  this  section,  we  consider  the 
processes  that  are  followed  when  defining  an  OnDemand  report,  along  with  hints 
and  tips  to  help  in  the  design  and  implementation  process. 

The  system  components  which  are  required  for  creating,  retrieving,  and  viewing 
an  OnDemand  report  are  a  storage  set,  an  application  group,  an  application,  and 
a  folder.  These  elements,  in  combination,  allow  the  OnDemand  administrator  to 
define  and  create  a  report  definition  which  can  then  be  used  to  index  and  load 
data  into  OnDemand.  Figure  2-1  illustrates  the  relationship  of  these  elements  in 
a  typical  OnDemand  system. 
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2.1.1  Storage  sets 

A  storage  set  contains  one  or  more  storage  nodes  that  can  be  used  by  several 
application  groups  which  have  the  same  archive  storage  requirements.  For 
example,  a  storage  set  can  be  used  to  maintain  data  from  different  application 
groups  that  need  to  retain  documents  for  the  same  length  of  time  and  need  the 
data  to  be  kept  on  the  same  type  of  media.  Different  storage  sets  can  be  created 
to  handle  different  data  retention  requirements.  One  storage  set  could  be  set  up 
to  maintain  data  on  cache-only  storage,  another  could  be  set  up  to  point  to  an 
archive  storage  to  maintain  data  for  three  years  on  optical  media.  Business 
practices  and  legal  requirements  determine  the  storage  management  design 
required. 

A  more  in-depth  look  into  storage  management  can  be  found  in  Chapter  5, 
“Storage  management”  on  page  85.  However,  excerpts  from  that  chapter  are 
repeated  here  to  introduce  the  various  report  administration  related  topics. 


2.1.2  Application  groups 

An  application  group  is  a  collection  of  one  or  more  applications  which  contain 
common  indexing  and  storage  management  requirements.  The  application  group 
contains  the  database  information  which  is  used  to  load,  search  for,  and  retrieve 
reports.  The  application  group  defines  the  data  which  to  be  loaded  into  the 
database.  In  the  following  sections  we  take  a  closer  look  at  aspects  of  application 
group  definition  which  can  contribute  to  a  successful  OnDemand  system 
implementation. 

Database  information 

The  database  information  section  of  the  application  group  definition  process 
(Figure  2-2)  requires  that  decisions  be  made  concerning  the  number  of  rows  to 
be  stored  in  each  database  table  and  the  number  of  report  loads  to  be  included 
in  each  database  table.  These  values  are  important  to  system  performance  and 
maintenance. 


Chapter  2.  Administration  19 


Figure  2-2  Database  information 

Maximum  rows 

The  maximum  rows  value,  which  determines  how  many  data  rows  will  be  loaded 
into  each  database  table,  is  used  for  segmenting  the  index  data  and  determining 
when  to  close  a  database  table  and  open  a  new  one.  The  default  value  of 
10,000,000  rows  is  recommended  for  balancing  the  performance  of  data  loads 
and  queries.  The  number  of  rows  specified  should  be  large  enough  to  handle  the 
largest  possible  input  report  file.  The  value  should  be  decreased  if  there  is  a 
small  amount  of  data  associated  with  the  application  group,  thereby  increasing 
query  performance  without  adversely  affecting  data  load  performance. 

Loads  per  database  table 

The  number  of  loads  per  database  table  can  be  set  to  multiple  or  single.  If 
multiple  loads  is  chosen,  every  time  that  a  report  is  loaded  into  an  application 
group,  the  index  records  are  added  to  the  database  table  that  is  currently  open 
for  the  application  group.  When  the  current  application  group  table  reaches  the 
maximum  rows  value,  the  table  is  closed  and  a  new  table  is  opened.  We 
recommend  using  multiple  loads  per  database  table. 
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If  single  load  is  chosen,  a  new  database  table  is  used  for  each  load  of  a  report 
into  the  application  group.  The  maximum  rows  value  is  used  to  calculate  the 
space  allocation  for  the  single  load  tables.  Single  load  is  a  good  choice  if  the 
reports  being  loaded  are  not  tightly  related,  such  as  weekly  or  monthly  reports 
which  may  only  have  the  report  date  as  an  index  value. 

Storage  management 

The  storage  management  settings  (Figure  2-3)  determine  how  long  report  data 
and  indexes  will  be  kept  in  cache  storage  before  being  expired.  There  are  also 
options  that  determine  how  soon  data  will  be  migrated  to  archive  storage  after 
the  report  load  is  completed. 


Figure  2-3  Application  group  storage  management 
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Cache  data 

The  cache  data  setting  determines  if  the  report  data  will  be  stored  in  disk  cache, 
and  if  so,  how  long  it  will  be  kept  in  cache  before  it  is  expired.  If  the  cache  data  for 
nn  days  parameter  is  checked,  then  the  search  cache  is  always  selected.  The 
search  cache  determines  whether  OnDemand  searches  cache  storage  when 
users  retrieve  documents  from  the  application  group.  When  you  set  the  cache 
data  to  No,  you  can  configure  OnDemand  to  retrieve  existing  documents  from 
cache  storage  while  preventing  new  documents  from  being  copied  to  cache 
storage.  If  you  choose  not  to  store  reports  in  cache,  a  storage  set  that  supports 
archive  storage  must  be  selected. 


Note:  Data  that  is  retrieved  often  should  generally  remain  in  cache  until  it  is  no 
longer  needed  by  90%  of  OnDemand  users. 


Life  of  data  and  indexes 

The  life  of  data  and  indexes  settings  determine  the  length  of  time  that  report 
data,  indexes  and  resources  are  maintained  in  the  OnDemand  system  before 
they  are  deleted  from  an  application  group.  The  report  data,  indexes  and 
resources  can  be  maintained  indefinitely  if  set  to  never  expire,  or  may  be  kept  for 
up  to  273  years.  After  the  maintenance  threshold  has  been  reached,  the 
expiration  processing  can  be  used  to  expire  the  data  from  the  system. 

Expiration  type 

The  expiration  type  determines  how  report  data,  indexes  and  resources  are 
expired.  If  the  expiration  type  is  load,  an  input  file  at  a  time  can  be  deleted  from 
the  application  group.  The  latest  date  in  the  input  data,  and  the  life  of  data  and 
indexes  determines  when  OnDemand  will  delete  the  data.  Data  that  has  been 
stored  in  archive  storage  will  be  deleted  by  the  storage  manager  based  on  the 
archive  expiration  date.  We  recommend  load  as  the  expiration  type. 

If  the  expiration  type  is  segment,  a  segment  of  data,  which  is  a  database  file 
containing  index  values  for  an  application  group,  at  a  time  is  deleted  from  the 
application  group.  The  segment  must  be  closed  and  the  expiration  date  of  every 
record  in  the  segment  must  have  been  reached.  If  small  amount  of  data  are 
loaded  into  the  application  group,  and  the  maximum  rows  value  is  high,  the 
segment  may  be  open  for  a  long  period  of  time  and  the  data  will  not  be  expired 
for  the  period. 

If  the  expiration  type  is  document,  a  document  at  a  time  is  deleted  from  the 
application  group.  Storing  with  an  expiration  type  of  document  will  cause  the 
expiration  process  to  search  through  every  document  in  the  segment  to 
determine  if  the  expiration  data  has  been  reached,  which  may  result  in  long 
processing  times. 
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When  the  arsmaint  expiration  process  is  run,  data  will  only  be  deleted  from  the 
application  group  if  the  upper  threshold  for  the  size  of  cache  storage  has  been 
reached.  By  default,  the  cache  threshold  is  80  percent.  A  lower  threshold  can  be 
forced  by  the  expiration  command  parameters.  However,  unless  there  is  some 
reason  that  cache  needs  to  be  cleared,  leaving  data  in  cache  will  improve 
retrieval  performance. 

The  iSeries  does  not  use  a  cache  upper  threshold.  If  the  cache  data  for  days 
duration  has  passed  and  DSM  is  run,  then  the  data  is  deleted  from  cache 
immediately. 

Field  information 

Field  information  (Figure  2-4)  is  used  to  define  the  attributes  of  the  database 
fields  to  make  up  the  OnDemand  report  index  data.  These  attributes  determine 
the  characteristics  of  the  index  data  and  control  many  aspects  of  loading  and 
processing  data  in  the  system.  A  database  field  must  be  added  for  each  index 
value  required  by  applications  to  be  part  of  the  application  group. 

If  multiple  applications  will  be  part  of  the  application  group,  an  application  ID  field 
must  be  included  to  uniquely  identify  each  application  in  an  application  group. 

If  it  is  possible  that  more  than  one  application  will  be  part  of  an  application  group, 
you  should  include  the  application  ID  field. 


Note:  Be  sure  that  all  of  the  database  fields  needed  are  included  before  the 
application  group  is  added  to  the  OnDemand  system.  Database  fields  cannot 
be  added  after  the  application  group  has  been  created. 
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Figure  2-4  Application  group  field  information 


Next  we  consider  the  following  field  information  attributes  in  detail: 

►  Type 

►  Segment 

►  Application  ID  field 

Type 

The  type  attribute  determines  the  manner  in  which  that  database  field  is  used  by 
OnDemand.  There  are  three  main  types  of  attributes:  index,  filter,  and  not  in 

database. 
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A  field  should  have  a  type  of  index  if  it  is  used  to  uniquely  identify  a  document  or 
if  it  is  frequently  used  when  searching  for  documents  in  the  application  group. 
Designating  a  field  as  an  index  serves  to  enhance  query  performance  but 
increases  required  overhead  during  loading  and  database  maintenance.  A 
separate  index  table  is  created  and  maintained  for  application  group  fields  that 
are  designated  as  indexes.  These  index  tables  are  searched  first  when  a  folder 
query  is  run  in  order  to  quickly  pinpoint  the  documents  that  are  to  be  included  in 
the  document  hit  list. 

A  field  should  have  a  type  of  filter  if  it  does  not  uniquely  identify  a  document  of 
the  file  and  that  it  is  usually  used  in  conjunction  with  an  index  field  during  folder 
queries. 


Important:  Folder  queries  using  filter  fields  alone  results  in  a  sequential  scan 
through  database  tables.  An  index  field  should  always  be  included  in  folder 
queries.  For  more  information  about  folder,  see  2.1 .4,  “Folders”  on  page  28. 


A  field  should  have  a  type  of  not  in  database  if  the  field  contains  the  same  data 
value  for  every  document  in  the  input  data.  A  value  for  that  field  will  be  stored  in 
the  segment  table  pointing  to  the  database  index  records  rather  than  storing  the 
same  value  over  and  over  again  in  each  row  of  the  database. 

A  thorough  understanding  of  the  way  that  users  will  be  searching  for  documents 
in  the  system  is  required  before  making  decisions  about  which  fields  should  be 
indexes  and  which  fields  should  be  filters.  Only  fields  that  to  be  heavily  used 
when  searching  for  and  retrieving  documents  should  have  a  type  of  index.  An 
index  field  should  always  be  included  in  a  folder  query. 

Segment 

Segment  is  the  date  or  date/time  field  that  is  used  to  limit  the  number  of  tables 
that  are  searched  during  a  folder  query.  If  the  application  group  is  defined  for 
multiple  loads  per  database  table,  it  is  highly  recommended  that  a  segment  date 
be  defined  for  the  application  group.  By  using  a  segment  date  to  limit  folder 
queries  to  a  single  table  or  a  limited  set  of  tables,  performance  is  significantly 
improved.  The  segment  date  is  especially  important  for  application  groups  that 
contain  a  large  amount  of  data. 


Note:  The  date  field  that  is  used  for  the  segment  date  should  always  have  a 
type  of  filter.  By  default,  an  index  is  created  for  the  segment  date  and  setting 
the  segment  date  to  a  type  of  index  would  create  unnecessary  overhead. 
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Application  ID  field 

The  application  ID  field  is  used  to  identify  an  application  within  an  application 
group  when  you  create  an  application  group  that  contains  more  than  one 
application.  The  database  mapping  fields  are  used  to  map  the  value  to  be  stored 
in  the  database  as  the  label  that  is  displayed  for  folder  queries  and  in  the 
subsequent  query  hit  list.  A  query  can  be  made  against  a  specific  application  in 
an  application  group  or  against  all  of  the  applications  in  an  application  group. 


2.1.3  Applications 

An  application  defines  the  data  that  is  to  be  indexed  and  loaded,  associates  the 
data  with  an  application  group,  specifies  the  type  of  indexing  process  to  be 
performed  on  the  data,  defines  any  logical  views  to  be  put  in  place  for  the  end 
users,  and  determines  any  special  print  options  to  be  used  with  the  data.  Next  we 
consider  some  of  the  load  information  attributes  in  this  section. 

Load  information 

Load  information  specifies  the  processing  and  resource  information  that  the 
OnDemand  loader  uses  to  load  the  input  data  onto  storage  volumes  and  to  load 
the  associated  index  data  into  the  OnDemand  database.  File  format, 
preprocessor,  and  postprocessor  parameters  (Figure  2-5)  are  defined  as  part  of 
load  information. 

►  File  format:  Provides  settings  which  control  how  the  OnDemand  system 
compresses  and  stores  documents  and  resources. 

►  Preprocessor:  Specifies  processing  that  is  carried  out  on  database  fields 
prior  to  indexing  data. 

►  Postprocessor:  Specifies  a  system  command  or  exit  program  which  will  be 
run  against  an  index  file  before  the  index  records  are  loaded  into  the 
database. 
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Figure  2-5  Application  load  Information 

Next  we  ciscuss  the  details  of  large  object  support  and  the  ways  that  this 
enhances  system  performance. 
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Large  object  support 

Large  object  support  is  used  to  improve  load  and  retrieve  performance  by 
dividing  the  document  into  smaller  parts  for  loading  and  creating  index 
information  based  on  this  document  segmentation.  Documents  will  be  retrieved 
faster  due  to  the  smaller  segment  sizes  that  are  being  sent  across  the  network. 

When  a  document  is  retrieved  for  viewing,  only  the  first  part  of  the  document  is 
returned  from  the  server  to  the  client.  Additional  parts  of  the  document  are  sent 
from  the  server  to  the  client  as  the  user  moves  to  different  pages  in  the 
document.  ACIF  and  OS/400  are  the  two  indexers  that  can  be  used  to  enable 
large  object  support.  Invoking  large  object  support  generates  an  INDEXOBJ=ALL 
entry  in  the  indexing  parameters  which  enables  the  generation  of  large  object 
indexing  information. 

When  large  object  is  selected,  the  number  of  pages  parameter  must  also  be 
specified.  Number  of  pages  determines  how  many  pages  will  be  included  by 
OnDemand  in  each  large  object  segment. 

If  large  object  is  not  selected,  the  compressed  object  size  parameter  is  included 
in  the  load  information.  The  compressed  object  size  specifies  the  size  in  kilobytes 
of  each  stored  block  of  data.  We  recommend  the  default  size  of  100  KB  blocks. 


2.1.4  Folders 

A  folder  is  the  interface  that  allows  a  user  to  search  for  reports  and  documents 
that  have  been  stored  in  the  OnDemand  system.  The  user  enters  index  search 
criteria  for  an  application  group  into  the  folder  search  fields  and  a  document  hit 
list  is  constructed  based  on  the  results  of  the  query.  The  folder  can  be 
customized  to  provide  the  look  and  feel  that  is  desired  for  the  end  users  of  the 
system.  The  folder  definition  process  allows  the  OnDemand  administrator  to 
grant  specific  permissions  for  users  of  the  folders.  We  now  consider  several 
folder  parameter  settings  (Figure  2-6)  that  can  have  an  impact  on  document 
retrieval  performance. 
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Figure  2-6  Folder  general  Information 

Display  document  location 

The  display  document  location  setting  (Figure  2-6)  causes  OnDemand  to  display 
an  icon  next  to  each  entry  in  a  hit  list  returned  by  a  folder  query.  The  possible 
locations  are  cache  storage,  archive  storage,  and  external  storage.  Enabling  this 
feature  should  be  done  with  care. 
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Important:  The  display  document  location  function  can  result  in  degraded 
search  performance  due  to  the  fact  that  the  storage  location  information  for 
every  document  returned  for  the  hit  list  must  be  retrieved  from  the  OnDemand 
object  server. 


Note  search 

The  note  search  setting  determines  when  the  end  user  will  be  notified  that  a  note 
exists  for  a  report  document.  If  the  annotation  parameter  in  the  application  group 
is  set  to  NO,  the  note  search  parameter  determines  when  OnDemand  searches 
the  database  for  annotations  and  then  notifies  the  end  user  of  the  annotations. 
The  possible  options  are: 

►  Hit  list:  When  a  folder  query  is  run,  OnDemand  searches  for  annotations  and 
an  note  icon  is  displayed  next  to  each  document  in  the  resulting  hit  list  which 
contains  an  annotation.  The  hit  list  option  has  a  direct  performance  impact  on 
the  generation  of  the  document  list. 

►  Retrieve:  OnDemand  searches  for  annotations  when  the  user  selects  a 
document  for  display.  We  recommend  using  Retrieve,  the  default  option. 

►  Note:  OnDemand  searches  for  annotations  when  the  user  selects  the  note 
command  when  viewing  a  displayed  document. 

We  recommend  setting  the  annotation  parameter  in  the  application  group 
advanced  settings  to  handle  annotation  storage  and  display.  When  the 
application  group  annotation  parameter  is  set  the  YES,  an  annotation  flag  is  set  in 
the  database  when  a  user  adds  an  annotation  to  a  document.  When  an 
annotation  exists  for  a  document,  a  note  icon  is  displayed  in  the  folder  document 
hit  list. 

Maximum  hits 

Maximum  hits  (Figure  2-7)  sets  the  maximum  number  of  document  hit  list  entries 
to  be  returned  by  a  folder  query.  Limiting  the  number  of  hits  that  can  be  returned 
from  a  query  will  prevent  performance  degradation  that  may  be  experienced  if  an 
extremely  large  result  is  returned  from  a  query.  If  a  query  results  in  a  very  large 
hit  list  that  takes  a  long  time  to  create,  the  cancel  operation  function  on  the 
OnDemand  client  can  be  used  to  stop  the  creation  of  the  hit  list. 


Note:  OnDemand  does  not  guarantee  the  order  in  which  the  hits  will  be 
retrieved  from  the  database.  If  the  hit  list  size  is  limited,  it  is  possible  that  you 
will  not  see  the  most  recent  documents.  If  the  most  recent  documents  in  the 
application  group  are  needed,  the  query  will  need  to  be  qualified  in  a  way  that 
results  in  a  hit  list  which  does  not  exceed  the  maximum  hits  parameter. 
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Figure  2-7  Folder  permissions 

Secondary  folder 

The  secondary  folder  parameter  (Figure  2-7)  is  used  to  manage  the  number  of 
folders  that  a  user  is  presented  with  when  they  log  on  to  the  OnDemand  system 
and  their  list  of  folders  is  displayed.  By  default,  OnDemand  will  present  a  list  of 
the  primary  folders  that  a  user  is  authorized  to  access.  Marking  a  folder  as  a 
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secondary  folder  will  reduce  that  size  of  the  initial  folder  list.  All  folders  that  the 
user  is  authorized  to  view  may  be  displayed  by  selecting  the  show  all  folders 
option  in  the  OnDemand  client. 

Text  search 

Text  search  is  used  to  search  documents  that  contain  a  specific  word  or  phrase 
before  the  document  hit  list  is  built.  Only  documents  which  contain  the  specified 
word  or  phrase  will  be  returned  as  part  of  the  hit  list.  The  search  takes  place  on 
the  server. 

Using  text  search  allows  a  user  to  further  qualify  a  search  without  adding  the 
overhead  associate  with  adding  and  maintaining  additional  index  fields  to  the 
database.  Text  search  is  performed  on  the  documents  that  match  the  criteria  for 
the  other  query  fields.  For  example,  if  the  other  query  fields  are  date  and  account 
number,  text  search  will  be  performed  on  the  documents  that  match  the  specified 
date  and  account  number.  If  the  document  contains  the  text  search  string,  it  will 
be  returned  as  part  of  the  hit  list.  Text  search  fields  do  not  need  to  be  mapped  to 
database  fields. 

Text  search  string  can  be  a  word  or  a  phrase.  Only  one  text  search  field  can  be 
defined  per  folder.  The  only  valid  search  operator  is  EQUAL.  Wild  card  searches 
and  pattern  searches  are  not  allowed.  Text  search  is  not  case  sensitive. 

There  are  other  text  search  limitations  based  on  the  type  of  the  documents  to  be 
searched  and  the  platform  OnDemand  is  running.  Refer  to  the  latest  OnDemand 
documentation  for  details. 

To  create  a  text  search  field,  you  can  first  create  a  new  folder  using  the  Report 
Wizard  or  using  an  existing  folder.  Make  a  copy  of  the  new  folder  or  the  existing 
folder,  and  rename  the  copied  folder.  Add  a  field,  with  the  field  type  as  Text 
Search,  to  the  copied  folder  (Figure  2-8).  Select  Show  Search  String  option  in  the 
Options  menu.  This  causes  the  system  to  highlight  the  searched  text  string  when 
the  document  is  opened.  If  Autoview  in  the  Options  menu  is  set  to  First 
Document  or  Single  Document,  the  document  automatically  displays  with 
searched  string  highlighted.  Single  Document  option  causes  the  document  to  be 
automatically  displayed  if  only  one  document  meets  the  search  criteria.  First 
Document  option  causes  the  first  document  in  the  hit  list  to  be  displayed 
automatically  with  highlighted  searched  string. 

To  use  the  text  search  field,  open  the  folder  with  a  pre-defined  text  search  field 
and  perform  a  text  search.  When  a  document  returned  by  a  text  search  is  opened 
for  viewing,  the  viewer  will  be  positioned  to  the  first  line  in  the  document  that 
contains  the  text  search  string.  The  Find  Next  option  can  be  used  to  move  to 
other  occurrences  of  the  string  in  the  document. 
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Figure  2-8  Folder  field  definition  -  text  search  field 


Note:  You  can  still  perform  a  standard  search  with  this  folder.  You  do  not  have 
to  specify  a  text  search  every  time. 


One  of  the  advantages  of  the  text  search  function  is  that  the  search  is  performed 
on  the  server.  The  speed  of  search  is  based  on  the  power  of  the  server  that  is 
running  OnDemand.  The  disadvantage  is  the  performance  hit  that  may  be 
incurred  by  the  system.  The  larger  the  number  of  documents  that  matches  the 
other  query  fields,  the  longer  it  will  take  for  the  text  search  to  be  performed  on 
this  document  list  in  order  to  build  the  resulting  hit  list. 
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Users  should  always  fully  qualify  the  queries  to  bring  back  only  the  specific 
documents  that  they  need  to  view.  Any  sort  of  wild  card  search  in  conjunction 
with  a  text  search  could  have  a  severe  impact  on  performance. 


2.2  User  and  group  administration 

When  designing  an  OnDemand  system,  decisions  must  be  made  concerning  the 
best  way  to  implement  the  many  authority  structures  that  are  available  for  users 
and  administrators  of  the  system.  The  span  of  control  for  the  administration  of  the 
system  must  be  considered  along  with  the  level  of  user  access  to  the  data  stored 
in  the  system.  How  many  different  administrators  will  be  required?  Will  all 
administrators  have  system  administrator  authority  or  will  different  administrators 
have  different  levels  of  authority?  What  is  the  most  effective  way  to  restrict  a 
user’s  access  to  only  the  data  that  is  necessary  to  carry  out  their  jobs? 

The  answers  to  these  questions  depend  on  the  size  of  the  system,  the  degree  of 
centralization  to  be  exercised  over  system  administration,  and  the  nature  of  the 
data  and  the  business  needs  of  the  users. 

Centralized  or  decentralized? 

In  a  system  design  which  exercises  centralized  control,  one,  or  a  very  few 
administrators  would  be  granted  System  Administrator  authority.  A  centralized 
system  would  typically  be  used  when  the  number  of  reports  and  users  to  be 
added  to  the  system  are  small.  Centralized  administration  is  also  appropriate 
where  resources  are  limited  and  only  one  person  may  have  the  skills  and 
knowledge  to  perform  the  system  administration  tasks,  or  where  one  user  group 
will  be  performing  all  administration  tasks. 

In  a  system  design  with  decentralized  control,  different  users  are  granted 
different  levels  of  administrative  authority.  For  instance,  you  may  have  users 
which  have  the  authority  to  create  users  and  groups.  Other  users  may  have  the 
authority  to  create  application  groups  and  folders  while  still  other  users  may  be 
given  full  system  administration  authority. 

The  skill  level  of  the  users  may  be  a  determining  factor  in  the  degree  of  authority 
that  is  granted.  It  will  take  a  more  skilled  user  to  define  indexes  and  report 
parameters  than  to  set  up  users  and  groups.  A  decentralized  system  would 
typically  be  used  when  data  from  different  sources  is  stored  on  the  same 
OnDemand  system  but  must  be  maintained  independent  of  other  data. 
Decentralization  also  makes  sense  when  report  loading  and  processing  needs  to 
limited  to  a  specific  group  of  users  for  security  purposes  or  when  administrators 
that  add  users  and  groups  must  be  prevented  from  accessing  report  data. 
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The  decision  on  whether  to  use  a  centralized  or  a  decentralized  administration 
model  is  best  made  before  any  data  is  set  up  in  the  system.  Even  though  the  type 
of  administration  chosen  can  be  changed  at  a  later  date,  the  amount  of  work 
involved  in  making  that  change  will  be  greater  than  the  amount  of  work  that 
would  be  necessary  to  study  the  requirements  of  the  system  and  put  into  place 
the  most  appropriate  administration  policies  from  the  beginning. 


2.2.1  User  types,  authorities,  and  functions 

There  are  generally  four  different  types  of  users  in  an  OnDemand  system.  Each 
has  a  different  level  of  access,  authority,  and  responsibility  in  the  system. 

►  End  user:  End  users  log  in  and  query  the  system  to  retrieve  documents  and 
reports  for  viewing. 

►  User  administrator:  User  administrators  add  end  users  or  other  user 
administrators  to  the  system. 

►  Report  administrator:  Report  administrators  define  the  application  groups, 
applications,  and  folders  to  be  part  of  the  system.  They  are  responsible  for 
knowing  the  report  and  document  data  and  for  defining  the  indexes  to  be 
extracted  from  the  data  and  stored.  Report  administrators  are  also 
responsible  for  designing  the  end  user  interface  to  the  reports  through  the 
folder  definition  process  and  for  controlling  access  authority  to  the  reports 
which  they  design,  index,  and  load. 

►  System  administrator:  System  administrators  have  the  highest  level  of 
authority  in  an  OnDemand  system.  They  have  authority  for  all  system 
functions  and  can  grant  other  users  the  authority  to  perform  various  tasks. 
The  system  administrator  is  the  only  level  of  authority  which  can  grant  create 
group  authority,  create  storage  sets,  and  define  system  printers. 

Once  the  administrative  tasks  and  levels  of  authorities  are  understood,  decisions 
must  be  made  concerning  the  span  of  control  in  the  system.  Is  it  better  to  have 
one  user  control  all  access  and  functions  in  the  OnDemand  system  or  is  it  better 
to  spread  the  administrative  tasks  among  several  users  in  order  to  smooth  the 
workload  based  on  system  requirements?  The  answer  to  this  question  will 
depend  on  the  factors  that  were  discussed  previously  concerning  centralized  or 
decentralized  administrative  control. 

As  stated  earlier,  a  centralized  administrative  plan  is  best  suited  for  an 
OnDemand  system  with  a  small  number  of  users  and  relatively  few  reports  which 
need  to  be  defined.  In  the  next  section,  we  focus  on  decentralized  system  and 
discuss  the  different  aspects  of  a  decentralized  administrative  plan. 
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2.2.2  Decentralized  system  administration 

OnDemand  provides  enough  flexibility  in  types  of  users  and  in  levels  of  authority 
to  allow  many  different  methods  to  decentralize  administrative  control  of  a 
system.  In  most  cases,  the  need  to  control  access  to  specific  data  or  to  control 
access  to  specific  OnDemand  objects  is  the  determining  factor  in  choosing  a 
decentralized  administrative  model.  Next  we  examine  two  decentralized 
administration  scenarios.  One  is  the  object  type  model  and  the  other  is  the  object 
owner  model. 

Object  type  model 

The  object  type  model  (Figure  2-9)  is  used  to  control  access  to  specific  objects  in 
the  OnDemand  system.  All  users  and  groups  in  the  system  are  created  and 
maintained  by  a  user  administrator.  Reports  in  the  system  are  created  and 
maintained  by  a  report  administrator.  The  object  type  model  lends  itself  to  the 
division  of  administrative  tasks  based  on  security  requirements  or  skill  level.  The 
administrator  that  adds  users  and  groups  does  not  necessarily  need  access  to  all 
report  data.  The  skill  level  required  to  administer  users  is  much  lower  than  the 
skill  level  that  is  required  to  analyze  data  and  to  create  and  administer  report 
definitions. 


Figure  2-9  Object  type  model  system  administration 
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Implementing  the  object  type  model 

When  putting  in  place  an  object  type  model,  the  OnDemand  system 
administrator  will  define  two  new  users.  A  report  administrator  will  be  defined 
and  be  given  authority  as  an  application  group  and  folder  administrator.  A  user 
administrator  will  be  defined  with  authority  to  create  users  and  to  create  groups. 

The  report  administrator  defines  and  creates  the  application  groups, 
applications,  and  folders  that  make  up  the  OnDemand  system.  In  this  role,  the 
report  administrator  is  responsible  for  determining  which  data  fields  in  the  report 
data  will  make  up  the  indexes  for  the  reports,  how  the  index  data  will  be  extracted 
from  the  report  data,  how  the  reports  will  be  loaded  into  the  system,  and  how 
long  the  report  data  and  indexes  will  be  maintained  in  the  system.  The  report 
administrator  also  controls  access  to  the  reports  that  are  created.  Access  can  be 
granted  to  individual  users  or  can  be  granted  to  user  groups.  The  use  of  groups 
for  access  control  will  simplify  the  task.  Simply  adding  a  user  to  a  group  with 
access  to  a  specified  report  will  prevent  the  need  to  grant  authority  to  each  user 
that  needs  access  to  a  report. 

The  user  administrator  will  add  users  to  the  system  and  will  create  groups  to 
which  users  may  be  added.  Any  user  added  to  the  group  will  have  access  to  all 
reports  that  may  be  accessed  by  members  of  the  group.  The  user  administrator 
will  also  add  the  report  administrator  to  the  groups  that  require  access  to  report 
data.  By  virtue  of  being  added  as  a  group  member,  the  report  administrator  will 
be  able  to  see  the  group  in  the  permissions  list  for  application  groups  and  folder 
and  can  grant  access  permission  to  the  group.  A  report  administrator  does  not 
automatically  have  access  to  users  and  groups  when  accessing  permission  lists. 

Table  2-1  summarizes  different  types  of  the  administrators  and  their 
corresponding  roles. 


Table  2- 1  Administrator  roles  in  object  type  model 


Administrator  Type 

Administrative  Tasks 

System  administrator 

Create  Report  administrators 

Create  User  administrators  with  create  groups  authority 

Create  and  maintain  storage  sets 

Create  and  maintain  system  printers 

Report  administrator 

Create  and  maintain  application  groups 

Create  and  maintain  applications 

Create  and  maintain  folders 

User  administrator 

Create  and  maintain  users 

Create  and  maintain  groups 
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Object  owner  model 

The  object  owner  model  (Figure  2-1 0)  is  a  design  which  allows  for  report  security 
based  on  limiting  data  access  to  a  small  group  of  users.  The  users  and  reports 
on  the  system  are  created  and  maintained  by  administrators  which  only  work 
with  that  group  of  users  and  reports.  Other  users  and  reports  that  exist  in  the 
OnDemand  system  will  be  created  and  maintained  by  a  different  set  of 
administrators.  This  allows  the  reports  and  users  to  exist  independently  from 
other  groups  of  users  and  reports  and  they  are  not  accessible  by  other  groups  in 
the  system. 
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Companies  that  provide  billing,  payroll,  accounting,  and  bill  presentment  services 
for  a  number  of  clients  would  be  good  candidates  for  the  object  owner  model. 
Users  from  one  company  would  be  completely  isolated  from  the  data  and  users 
of  another  company.  There  would  be  separate  administrators  for  each  company 
that  is  being  serviced. 

Implementing  the  object  owner  model 

When  putting  in  place  an  object  owner  model,  care  has  to  be  taken  concerning 
access  to  sensitive  data.  Data  from  several  different  sources  will  be  residing  on 
one  OnDemand  System.  Each  group  of  data  will  need  to  be  accessible  by  a 
distinct  group  of  users.  For  each  group  of  data,  the  OnDemand  system 
administrator  will  define  a  report  administrator  and  a  user  administrator. 

The  report  administrator  is  defined  with  the  authority  to  create  and  maintain 
application  groups  and  folders.  The  report  administrator  will  only  have  authority 
over  the  application  groups,  applications,  and  folders  that  he  or  she  creates. 

The  user  administrator  is  defined  with  the  authority  to  create  users  and  to  create 
user  groups.  The  user  administrator  will  only  have  authority  over  the  users  and 
user  groups  that  he  or  she  creates. 

The  OnDemand  system  administrator  must  give  the  user  administrator  authority 
of  the  report  administrator.  This  authority  will  allow  the  user  administrator  to  add 
the  report  administrator  to  the  groups  which  have  access  to  the  reports  which  the 
report  administrator  will  be  creating.  This,  in  turn,  allows  the  report  administrator 
to  view  and  add  members  of  the  groups  to  the  permissions  list  of  the  application 
groups  and  folders  that  he  or  she  creates. 

The  responsibilities  of  the  user  administrators  and  report  administrators  are  the 
same  in  both  the  object  type  model  and  the  object  owner  model.  The  difference  is 
that  in  the  object  type  model,  the  administrators  have  authority  over  all  users  and 
reports  in  the  system,  while  in  the  object  owner  model,  (Table  2-2)  the 
administrators  only  have  authority  over  the  users  and  reports  which  they  have 
created. 


Table  2-2  Administrator  roles  in  object  owner  model 


Administrator  Type 

Administrative  Tasks 

System  administrator 

Create  a  Report  administrator  with  create  application  groups 
and  create  folders  authority 

Create  a  User  administrator  with  create  groups  authority 

Create  and  maintain  storage  sets 

Create  and  maintain  system  printers 
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Administrator  Type 

Administrative  Tasks 

Report  administrator 

Create  and  maintain  application  groups 

Create  and  maintain  applications 

Create  and  maintain  folders 

User  administrator 

Create  and  maintain  users 

Create  and  maintain  groups 

2.2.3  Summary 

Choosing  the  right  administration  model  is  an  important  decision  in  the  design  of 
an  OnDemand  system.  The  following  table  (Table  2-3)  contains  general 
guidelines  which  can  be  taken  into  account  as  the  decision  concerning  an 
administration  model  is  being  made. 


Table  2-3  Administration  guidelines 


Environment 

Recommendation 

The  number  of  reports  and  users  to  add  to 
the  OnDemand  system  is  small  (less  than 
100). 

Centralized  system  administration 

Resources  are  limited  and  only  one  person 
will  perform  system  administrative  tasks. 

Centralized  system  administration 

All  of  the  system  administration  tasks  are 
performed  by  one  group. 

Centralized  system  administration 

Data  from  several  independent  sources  is 
maintained  on  the  same  OnDemand  system. 
The  data  must  be  kept  independent  of  other 
data  in  the  system.  Data  must  be  isolated 
and  access  are  only  allowed  for  users  with  a 
need  to  view  the  data. 

Decentralized  system  administration 
using  the  object  owner  model 

Report  processing  and  loading  must  be 
limited  to  a  group  of  users  for  security 
reason. 

Decentralized  system  administration 
using  the  object  type  model 

The  administrator  that  adds  and  maintains 
users  must  not  have  access  to  the  report 
data.  A  separate  administrator  performs 
report  administration  and  loading. 

Decentralized  system  administration 
using  the  object  type  model 
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Database  structure 


In  this  chapter  we  describe  the  OnDemand  database  structure  and  relationships 
between  the  tables.  We  list  all  of  the  system  control  tables  and  the  important  data 
table  structures.  Then  we  explain  the  relationship  between  the  tables  when 
loading  data,  show  how  a  search  is  performed  on  the  database  tables,  describe 
the  system  log,  and  discuss  special  considerations  for  DB2  on  OS/390. 

This  chapter  includes  the  following  topics: 

►  System  control  tables 

►  Main  data  table  structures 

►  Relationship  between  databases  when  loading  data 

►  Search  sequence  from  folder 

►  System  log 

►  Database  creation  and  relationship  on  z/OS 
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3.1  System  control  tables 

OnDemand  uses  system  tables  and  a  set  of  application  group  data  tables.  All 
system  control  tables  are  created  with  the  arsdb  command.  The  data  tables  are 
created  when  you  load  data  into  the  OnDemand  system. 

Table  3-1  shows  the  OnDemand  system  control  tables  with  their  descriptions. 


Note:  The  complete  table  name  is  composed  of  the  owner  name  (which  could 
be  the  database  name  or  the  instance  name)  and  the  table  name.  For 
example,  the  application  group  table  ARSAG  that  belongs  to  the  ODARCH  instance 
has  a  complete  table  name  of  ODARCH. ARSAG. 

For  iSeries,  the  complete  table  name  is  in  the  format  of  library/table  where  the 
library  name  is  always  the  same  as  the  instance  name.  For  example,  the 
application  group  table  ARSAG  that  belongs  to  the  default  QUSROND  instance  has 
a  complete  table  name  of  QUSROND/ARSAG. 


Table  3- 1  OnDemand  system  control  tables 


Table  name 

Purpose 

Description 

ARSAG 

application  group  table 

One  row  for  each 
application 

ARSAG2FOL 

field  mapping  table 

One  row  for  each 
application  group  field 
mapped  to  a  folder  field 

ARSAG FLD 

application  group  field 
table 

One  row  for  each  field 
defined  in  an  appl.  group 

ARSAG  FLDALIAS 

application  group  field 
alias  table 

One  row  for  each  database 
(internal)  and  displayed 
(external)  value  in  an  appl. 
group 

ARSAGPERMS 

application  group 
permissions  table 

One  row  for  every  user 
given  specific  permission 
to  an  appl.  group 

ARSANN 

annotation  table 

One  row  for  each 
annotation  added  to 

database 

ARSAPP 

application  table 

One  row  for  each 
application  defined  to 
OnDemand 
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Table  name 

Purpose 

Description 

ARSAPPUSR 

user  logical  views  table 

One  row  for  each  logical 
view  defined  for  a  specific 
user 

ARSFOL 

folder  table 

One  row  for  every  folder 
defined  in  OnDemand 

ARSFOLFLD 

folder  field  table 

One  row  for  every  folder 
field  defined  for  a  folder 

ARSFOLFLDUSR 

folder  user  field  table 

one  row  for  every  field 
provided  for  a  user  given 
specific  field  information 
for  a  folder 

ARSFOLDPERMS 

folder  permission  table 

One  row  for  every  user 
given  specific  permissions 
to  a  folder 

ARSGROUP 

group  table 

One  row  for  each  group 
defined  to  OnDemand 

ARSLOAD 

load  table 

the  loadJD  table 

ARSNAMEQ 

named  query  table 

One  row  for  each  private 
and  public  named  query 
defined  to  OnDemand 

ARSNODE 

node  table 

One  row  for  each  storage 
node  defined 

ARSPRT 

printer  table 

One  row  for  each  printer 
defined  in  OnDemand 

ARSPRTOPTS 

printer  options  table 

One  row  for  each  printer 
option 

ARSPRTUSR 

printer  user  table 

One  row  for  each  user 
access  this  printer 

ARSRES 

resources  table 

One  row  for  each  resource 

ID 

ARSSEG 

segment  table 

One  row  for  each  segment 
of  application  group  data 

ARSSET 

storage  set  table 

One  row  for  each  storage 
set 
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Table  name 

Purpose 

Description 

ARSSYS 

system  parameters  table 

One  row  for  the  entire 
system 

ARSUSER 

user  table 

One  row  for  each  user 
defined  to  OnDemand 

ARSUSRGRP 

users  in  group  table 

One  row  for  each  user 
assigned  to  an  OnDemand 
group 

ARSUSRGRPID 

user  group  ID  table 

Maintains  the  association 
of  users  with  user  owners 
and  their  authority  for 
groups 

dynamic  name 

application  group  data 
table 

One  row  for  each 
document  that  is  stored  in 
the  application  group 

Important:  We  do  not  recommend  updating  the  tables  using  DB2  system 
tools  such  as  SPUFI  and  DB2  Control  Center.  The  tables  should  only  be 
updated  by  the  OnDemand  Administration  GUI  or  OnDemand  commands. 


3.2  Main  data  table  structures 

The  OnDemand  data  tables  can  grow  rapidly.  It  is  important  to  understand  the 
structure  of  the  data  tables  and  the  relationship  between  the  data  tables. 

There  are  two  important  tables  we  need  to  examine  here,  the  segment  table 
(ARSSEG)  and  the  application  group  data  table  (ROOT.ag_internal_id).  The 
segment  table  contains  one  row  for  each  application  group  table.  Table  3-2 
shows  the  ARSSEG  table  structure. 


Table  3-2  ARSSEG  table  structure 


Column  Name 

Data  Type 

Size 

Index 

Description 

agid 

integer 

4 

Y 

application  group  ID 

table_name 

varchar 

18 

N 

appl.  group  segment  table 
name 

start_date 

bigint 

8 

Y 

segment  start  date 

stop_date 

bigint 

8 

Y 

segment  stop  date 
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Column  Name 

Data  Type 

Size 

Index 

Description 

post_date 

bigint 

8 

N 

currently  not  used 

closed_date 

bigint 

8 

N 

date  table  was  closed 

reimported_date 

bigint 

8 

N 

date  table  was  reimported 

last_update 

bigint 

8 

N 

last  update  to  table 

last_backup 

bigint 

8 

N 

last  table  backup 

last_stats 

bigint 

8 

N 

last  runstats 

mask 

integer 

4 

N 

location 

ins_rows 

integer 

4 

N 

inserted  rows 

upd_rows 

integer 

4 

N 

updated  rows 

del_rows 

integer 

4 

N 

deleted  rows 

mod_rows 

integer 

4 

N 

modified  rows 

max_rows 

integer 

4 

N 

maximum  number  of  rows 

Note:  The  field  definitions  for  ARSSEG  may  be  different  depending  on  platforms. 
For  instance,  z/OS  does  not  support  the  bigint  type;  therefore,  it  is  an  integer. 

The  start_date  and  the  stop_date  are  written  in  an  internal  OnDemand  format. 
Use  the  arsdate  command  to  get  the  normal  date  format.  For  example,  if  you 
get  11992  from  the  database,  use  arsdate  11992  and  the  system  will  return 
10/31/02. 

The  ARSEG  table  points  to  the  application  group  data  table  name  (second  column 
of  the  table,  table_name).  The  application  group  data  table  is  created  or  updated 
during  the  arsload  process.  It  contains  a  row  for  each  item  stored  in  the 
application  group. 

The  name  of  the  application  group  data  table  is  ag_internal_id,  where 
agjnternaljd  is  the  identifier  that  OnDemand  assigns  to  the  application  group 
when  it  is  created  with  the  administrative  client.  The  3-digit  application  group 
identifier  is  listed  on  the  Storage  Management  panel  of  the  administrative  client. 
Figure  3-1  shows  an  example.  In  this  case,  the  application  group  identifier  is 
EAA. 
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Update  an  Application  Group 


Figure  3- 1  Application  group  identifier  example 

Table  3-3  shows  the  application  group  data  table  structure. 

Table  3-3  AG_internai_id  table  structure 


Column  Name 

Data 

Type 

Description 

field_1 

varies 

First  user-defined  field  in  appl.  group 

field_n 

varies 

Last  user-defined  field  in  appl.  group.  You  can  have  up 
to  32  index  field  defined  in  OnDemand 

doc-name 

varchar 

Document  name  (object  name) 

doc_off 

integer 

Document  offset  in  the  object 

docjen 

integer 

Document  length 

comp_off 

integer 

Compression  offset 

compjen 

integer 

Compression  length 

annot 

char 

Annotation  flag 
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Column  Name 

Data 

Type 

Description 

comp_type 

char 

Compression  type 

resource 

integer 

Resource  identifier: 

0  stands  for  no  resource,  and 
n  stands  for  the  resource  ID  to  use 

pri_nid 

sm-int 

Primary  storage  node  identifier 

sec_nid 

sm-int 

Secondary  storage  node  identifier 

The  application  group  data  table  is  indexed  on  one  or  more  of  the  user-defined 
fields,  from  field_1  to  field_n. 


There  are  three  more  tables  which  may  grow  rapidly  during  the  lifetime  of  an 

OnDemand  system: 

►  The  annotation  table  (ARSANN),  if  a  lot  of  annotations  are  added  to  the 
documents.  The  system  creates  one  row  for  every  annotation.  This  means 
every  yellow  sticker  and  every  graphical  annotation  adds  one  row  to  this 
table. 

►  The  resource  table  (ARSRES),  if  a  lot  of  AFP  data  is  archived  in  an  OnDemand 
system  and  the  resources  such  as  formdef,  page  segments,  and  overlays  are 
often  changed.  The  resource  table  grows  depending  on  the  amount  of 
resources  added  and  changed. 

►  The  load  table  (ARSLOAD),  if  a  lot  of  arsload,  loading  data  to  the  system,  are 
done.  The  system  creates  one  row  for  each  load.  The  load  table  (see 
Table  3-4)  can  grow  to  a  multi-million  row  table  during  the  lifetime  of  an 
OnDemand  system. 


Table  3-4  ARSLOAD  table  structure 


Column  Name 

Data  Type 

Description 

agid 

integer 

application  group  identifier 

pri_nid 

smallint 

primary  storage  node  identifier 

sec_nid 

smallint 

secondary  storage  node  identifier 

name 

varchar(ll) 

name  of  the  load 

start 

integer 

start  date  in  segment 

stop 

integer 

end  date  in  segment 

exp_date 

integer 

expiration  date 
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The  load  ID  in  the  system  log  or  after  the  arsload  should  look  like  this: 
6850-25-0-15  FAA-95  77 -9577 . 


3.3  Relationship  between  databases  when  loading  data 

In  this  section,  we  present  an  example  that  shows  the  relationships  between  the 
databases  when  loading  data  to  an  OnDemand  system.  This  example  is  based 
on  a  check  application  which  has  4  index  fields  defined  as  customer_name, 
accout_nbr,  check_nbr,  and  balance.  There  is  a  one-to-one  relationship 
between  the  application  group  and  the  application. 

After  the  application  group  and  the  application  are  defined,  the  application  group 
gets  an  application  group  identifier,  agid ,  in  the  ARSAG  table  and  an  internal 
application  group  identifier,  agid_name.  Figure  3-2  displays  the  data  created  in 
the  ARSAG  table:  the  agid  is  5018,  and  the  agid_name  is  HAA. 

This  application  is  defined  to  create  a  new  application  group  data  table  every  10 
million  rows.  During  the  data  loading,  OnDemand  uses  the  agid  and  the 
agid_name  to  create  one  row  into  the  segment  table  (ARSSEG)  for  every  10  million 
rows.  The  important  pointer  in  the  ARSSEG  table  is  the  name  of  the  application 
group  data  table,  table_name,  where  the  index  values  (in  this  case,  the  4  defined 
index  values)  are  stored.  The  table_name  is  composed  of  the  agid_name  from 
the  ARSAG  table  plus  a  counter.  The  max_rows  in  ARSSEG  table  limits  the  total 
number  of  rows  can  be  stored  in  the  application  group  data  table.  The  ins_rows 
refers  to  the  actual  number  of  rows  stored  in  the  data  table.  Figure  3-2  displays 
the  two  rows  created  in  the  ARSSEG  table:  one  row  with  table_name  HAA1,  another 
HAA2.  Both  HAA1  and  HAA2  are  the  actual  names  of  the  application  group  data 
tables  created.  ARSSEG  keeps  track  of  the  maximum  rows,  and  the  currently 
inserted  rows:  one  is  10,000,000,  another  is  326,098. 

The  application  group  data  table  contains  the  doc_name  which  is  the  actual 
container  for  the  individual  document.  The  offset  and  the  document  length  are 
also  kept  in  this  table.  Figure  3-2  shows  the  first  row  has  an  offset  of  0,  and  the 
second  row  has  an  offset  of  the  document  length  of  the  first  row. 

Figure  3-2  shows  the  relationship  between  the  tables. 
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ARSAG  (application  group  table) 


name  (checks) 

agid .  (5018) 

agid_name  (HAA) 


ARSSEG  (segment  table) 


agid  table  name 

ins_rows 

max_rows 

5018  HAA1 

10.000.000 

10.000.000 

5018  HAA2 

326.098 

10.000.000 

HAA1  (application  group  data  table) 


custornerjiame 

account_nbr 

check  jibr 

balance 

doc_name  docjoffset 

docjength 

John  Smith 

123456789 

76543 

120.78 

2FAAA 

0 

21945 

Hans  Meyer 

234567890 

98765 

987.98 

2FAAA 

21945 

28063 

Jean  Ctipont  345678901 

. 10  Million  rows 

87654 

380.98 

2FAAA 

50008 

28595 

HAA2  (application  group  data  table) 


customer_name 

account_nbr 

check_nbr 

balance 

docjiame  docjoffset 

docjength 

Joan  Brown 

456784949 

87643 

245.78 

4FAAA 

0 

21945 

Maria  Gonzales 

574630988 

34512 

876.65 

4FAAA 

21945 

28063 

Luigi  Colletti  875632091 

. 326.098  rows 

85094 

1380.98 

4FAAA 

50008 

28595 

Figure  3-2  Relationship  between  system  tables  and  data  tables 

The  architecture  of  relating  one  application  group  to  one  or  more  application 
group  data  table  allows  OnDemand  an  unlimited  growth  of  index  space.  The 
maximum  table  size  is  a  limitation  of  the  database  subsystem  and  should  be 
configured  for  optimal  performance.  Because  this  architecture  enables  a  system 
to  create  new  tables  when  the  maximum  table  size  is  reached,  there  is  no  logical 
limitation  to  the  system;  rather  the  limitation  is  on  the  physical  resources  such  as 
processing  power,  disk  space,  object  servers,  and  storage  hardware. 


3.4  Search  sequence  from  folder 

To  better  understand  the  relationship  between  the  various  OnDemand  database 
tables,  we  describe  a  search  sequence  within  an  OnDemand  system  in  this 
section.  A  search  sequence  scans  through  multiple  OnDemand  databases,  we 
describe  the  detail  logical  flow  which  the  system  goes  through  during  an 
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OnDemand  search.  From  the  OnDemand  standard  windows  client,  a  search 
criteria  panel  is  shown  as  in  Figure  3-3.  In  our  example,  there  are  4  index  fields: 
name,  account,  Statement  Date,  and  Bal  ance.  The  example  shows  a  search  for 
a  specific  date  and  a  balance  amount. 


Baxter  Bay  Credit  Card  Statements  -  Search  Criteria  and  Document  List 


Search  Criteria 


name 
account 
Statement  Date 
Balance 


Like 

Like 

Equal  To 

3.05.1994 

Equal  To 

104,18| 

Figure  3-3  OnDemand  client  search  criteria  panel 

After  entering  these  values,  OnDemand  starts  searching  the  folder  table,  ARSFOL, 
to  find  out  the  folder  identification,  fid.  Figure  3-4  shows  that  the  fid  is  5022. 

After  getting  the  folder  information,  OnDemand  searches  the  ARSAG2F0L  table  for 
the  application  groups  associated  with  this  folder.  Figure  3-4  shows  the 
application  group  ID,  agid,  is  5020. 

In  general,  any  number  of  application  groups  can  be  connected  with  one  folder. 
In  our  example,  there  is  only  one  application  group  associated  with  this  folder. 
After  getting  agid  from  the  ARSAG2F0L  table,  the  system  searches  through  the 
segment  table,  ARSEG.  Based  on  the  date  (which  are  stored  in  OnDemand 
internal  format  in  the  Database),  OnDemand  gets  the  table_name  to  search  for 
the  index  values  (3.05.1 994  and  104,18)  in  the  application  group  data  table 
(FIAA1)  and  finds  the  matching  Statement_date  and  the  Balance,  and  returns 
these  values  to  the  client  in  a  search  result  list. 

To  retrieve  the  individual  document  within  this  result  list,  the  system  goes  back 
into  the  application  group  data  table  and  locates  the  document  offset  and  data 
set  (object)  and  retrieves  the  object  for  display  at  the  client. 

Figure  3-4  shows  the  details  of  this  search  sequence  from  a  folder. 
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Figure  3-4  Search  sequence  from  a  folder 


System  log 

System  log  is  an  application  group.  It  is  created  with  the  ARSSYSCR  program.  The 
application  group  identification  name  is  SL  and  a  4-byte  agid  is  added  as  well. 
You  will  find  SLXX  in  the  ARSEG  table  depending  on  how  big  your  system  log  is 
growing.  The  creation  of  a  new  system  log  table  is  based  on  the  number  of  rows 
on  the  Storage  Management  setting.  The  default  is  10  Million  rows.  This 
configuration  is  changeable. 


Database  creation  and  relationship  on  z/OS 

The  database  creation  and  the  allocation  of  space  for  tables  and  tablespace  of 
the  OnDemand  product  is  different  in  the  z/OS  environment  than  the  other  type 
of  environment.  In  general,  the  database  administrator  (DBA)  is  responsible  for 
the  allocation,  creation,  maintenance,  backup  and  recovery  of  the  database 
subsystem.  This  responsibility  is  not  changed  with  OnDemand  V7  on  z/OS. 
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System  tables 

Every  database  transaction  is  done  in  a  z/OS  environment.  The  standard  backup 
and  recovery  procedures  are  used  for  the  OnDemand-created  databases  and 
tables.  To  minimize  the  effort  of  creating  and  monitoring  the  OnDemand  data 
tables,  several  automated  table  creation  and  space  allocation  procedures  are 
implemented  into  the  product. 

All  system  tables,  as  mentioned  in  3.1,  “System  control  tables”  on  page  42,  are 
created  with  the  arsdb  program.  The  tables  are  created  in  one  tablespace.  This 
tablespace  is  created  during  the  installation  with  the  ARSTSPAC  member  in  the 
ODADMIN .  V7R1M0 .  SARINST  installation  file.  The  size  of  the  tablespace  is  set  there. 
Before  you  create  the  tablespace,  you  have  to  create  the  storage  group  and  the 
database.  It  is  important  that  the  owner  of  the  database  (the  submitter  of  the  job 
or  the  user  ID  which  is  set  by  the  “Set  current  SQLID  =’username’)  should 
match  the  entry  SRVR_INSTANCE_OWNER  in  the  ars .  i  ni  file. 

Figure  3-5  shows  the  relationship  between  the  configuration  file,  the  tablespace, 
and  the  system  tables. 


od.v7r1  mO.sarinst(arstspac) 


Figure  3-5  Relation  between  configuration  files,  tablespace,  and  system  tables 
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The  arsdb  program  provides  an  interface  between  the  database  manager  and 
OnDemand.  There  are  several  parameters  used  in  the  creation  and  dropping  of 
tables.  For  example,  to  create  initial  tables,  we  use  the  arsdb  -c  command.  Refer 
to  IBM  Content  Manager  OnDemand  forz/OS  and  OS/390  -  Configuration  Guide, 
GC27-1 373  for  more  details. 

The  arsdb  program  resides  in  the  USS  file  system  path  \usr\l  pp\ars\bi  n.  There 
are  several  parameters  along  with  the  arsdb  program.  Always  keep  in  mind  that 
the  ars.cfg  file  is  needed  to  determine  the  tablespace  name.  Today,  there  is  no 
way  to  set  the  individual  size  of  the  system  tables  because  there  is  only  one 
tablespace  associated  to  them.  The  creation  is  done  automatically  in  the 
background.  The  only  storage  allocation  size  parameter  which  is  changeable  is 
on  the  create  tablespace  statement  in  arstspac.  The  arsdb  command  allows  the 
creation  of  all  or  specific  tablespace.  It  is  possible  to  create  every  table 
individually  with  the  arsdb  -c  tablename.  Changing  the  ars_db_tabl  espace,  and 
create  another  tablespace  with  a  different  name,  and  assign  multiple  tablespace 
to  the  system  tables.  This  is  possible,  but  not  recommend.  The  best  way  to 
change  the  tablespace  is  the  ALTER  TABLESPACE  command  in  DB2. 

Data  tables 

The  data  tables  in  OnDemand  are  created  under  the  control  of  DB2  on  z/OS. 

Like  the  system  tables,  this  is  done  automatically  during  the  arsload  process.  It 
is  important  to  understand  how  OnDemand  on  z/OS  is  allocating  space  for  these 
tables,  because  they  can  grow  very  large. 

During  the  creation  of  an  application  group,  there  is  a  parameter  which  limits  the 
maximum  rows  for  one  table.  If  this  limit  is  reached,  OnDemand  creates  another 
data  table  during  the  arsload  process.  The  maximum  row  value  for  an  application 
group  table  is  customized  in  the  Advanced  section  of  the  General  tab  in  the  AG 
configuration  panels.  The  field  is  called  Maximum  Rows. 

The  allocation  of  space  is  done  automatically.  There  is  no  further  action  that 
needs  to  be  performed  by  the  DBA  except  to  set  up  the  backup  of  the  newly 
created  tables  and  plan  for  new  resources  needed  for  the  next  couple  of  months. 

There  are  four  major  factors  which  influence  the  amount  of  storage  needed  for 
the  OnDemand  database: 

►  The  number  of  index  and  filter  fields 

►  The  size  of  the  index  and  filter  fields 

►  The  number  of  indexed  items  per  month 

►  The  number  of  months  (years)  OnDemand  keeps  the  indexes  in  the  database 

Refer  to  IBM  Content  Manager  OnDemand  forz/OS  and  OS/390  -  Introduction 
and  Planning  Guide,  GC27-1438,  for  information  about  space  requirements. 
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OnDemand  for  z/OS  and  OS/390  allocates  its  tablespace  during  the  creation  of  a 
new  table  based  on  the  following  space  allocation  parameters: 

►  DBSIZE  /  2  for  primary  allocation 

►  Primary  allocation  /  4  for  the  secondary  allocation 

The  allocation  of  the  database  is  done  in  kilobytes.  The  allocation  values  depend 
on  the  maximum  row  limit  set  when  creating  the  application  group.  The  DBSIZE 
depends  on  the  number  of  index  fields  defined  in  the  application.  As  a  rule  of 
thumb,  the  calculation  of  the  DBSIZE  is  as  follows: 

Maximum  number  of  rows  *  Default  Table  Factor  /  records  per  page 

The  Default  Table  Factor  is  set  to  1 ,2  by  the  program.  The  records  per  page  value 
is  a  DB2  parameter.  For  more  information  about  records  per  page,  refer  to 
Chapter  8,  “Estimating  Disk  Storage”,  in  IBM  DB2  UDB  for  z/OS  and  OS/390  - 
Administration  Guide,  SC26-9931 . 


Note:  Based  on  this  calculation,  when  you  define  the  application  group,  make 
sure  you  lower  the  default  of  1 0  million  rows  if  you  only  want  to  store  a  small 
amount  of  data.  If  you  leave  the  10-million-row  default  unchanged,  OnDemand 
will  allocate  6  million  rows  at  the  primary  allocation. 
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Multiple  instances 


In  this  chapter  we  discuss  setting  up  multiple  instances  during  the  installation  for 
different  environments.  We  cover  in  detail  the  steps  needed  in  defining  and 
working  with  a  second  instance.  A  separate  section  is  included  for  each  platform: 
UNIX,  Windows  NT,  iSeries,  and  z/OS.  In  addition,  we  discuss  the  implications  of 
each  configuration. 

This  chapter  includes  the  following  topics: 

►  Multiple  instances  on  UNIX 

►  Multiple  instances  on  Windows  NT 

►  Multiple  instances  on  iSeries 

►  Multiple  instances  on  z/OS 


©Copyright  IBM  Corp.  2003.  All  rights  reserved. 
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4.1  Introduction 

An  OnDemand  instance  is  a  logical  server  environment  made  up  of  a  database, 
a  library  server,  and  one  or  more  object  servers.  Traditionally,  there  is  just  one 
OnDemand  instance  per  physical  system,  but  creating  multiple  instances  is  a 
nice  way  to  segment  applications.  Creating  multiple  instances  may  be  a  useful 
way  to  differentiate  between  a  development  environment  and  a  test  environment, 
or  to  allow  a  production  OnDemand  system  to  run  with  its  own  database. 
Creating  a  separate  instance  also  allows  for  having  multiple  databases,  each 
with  their  own  code  page. 


4.2  Multiple  instances  on  UNIX 

In  this  section,  we  describe  setting  up  multiple  instances  in  a  UNIX  environment. 

4.2.1  Defining  a  second  instance 

By  default,  the  initial  instance  on  any  library  server  is  archive.  By  updating  the 
OnDemand  configuration  files,  creating  the  DB2  instance,  defining  new 
tablespace  file  systems,  and  defining  cache  file  systems,  a  second  or  even  a 
third  instance  can  be  defined  on  the  same  physical  machine. 

Here  are  the  steps  to  follow  when  creating  a  second  instance: 

1 .  Create  user  and  home  directory. 

2.  Create  DB2  instance. 

3.  Update  configuration  files. 

4.  Create  OnDemand  database. 

5.  Initialize  System  Log  and  migration  facility. 

Create  user  and  home  directory 

The  first  step  that  must  be  taken  place  when  defining  a  new  instance  is  to  create 
the  user  ID  to  own  the  database  instance.  By  default,  the  initial  OnDemand 
database  is  archive  and  is  owned  by  the  user  archi  ve.  We  recommend  using  the 
same  naming  convention  for  each  additional  instance,  and  using  the  same  name 
for  both  the  owner  and  the  database  instance. 

Optionally,  you  can  allow  DB2  to  automatically  create  this  user  when  the 
database  instance  is  created;  but  you  may  want  to  create  the  user  manually,  so 
you  can  verify  that  the  proper  authorities  are  set  before  creating  the  instance.  You 
may  also  elect  to  use  an  existing  user.  This  instance  owner  must  belong  to  the 
sysadml  group.  Make  a  note  of  the  home  directory  for  the  user,  as  this  is  where 
the  SQL  libraries  will  be  installed  when  the  database  is  created. 
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The  default  user  and  the  default  instance  is  archi  ve.  In  our  scenario,  we  created 
a  user  called  ondtest  that  owns  the  ondtest  instance.  We  used  smitty  to  create 
this  user  and  add  the  user  ID  to  the  sysadml  group. 

Create  DB2  instance 

There  are  several  methods  of  creating  a  DB2  instance,  we  used  the  db2setup 
utility.  The  utility  will  ask  the  owner  and  home  directory  of  the  database  owner  — 
in  our  scenario,  we  used  the  ondtest  user  ID  we  created  earlier.  The  group  name 
for  the  database  must  be  sysadml.  We  recommended  that  you  use  the  same  user 
name  and  group  name  for  the  fenced  UDFs.  You  will  get  a  message  warning  you 
not  to  do  this.  If  OnDemand  is  the  only  application  running  on  the  machine,  we 
recommend  that  you  bypass  this  warning. 

Update  configuration  files 

There  are  four  configuration  files  that  must  be  updated  or  created.  They  are 
installed  with  OnDemand  at  installation  time.  For  the  AIX  platform,  they  are 
located  in  //usr/lpp/ars/config.  For  FIP-UX  and  Sun  Solaris,  they  are  located 
in  /opt/ondemand/config.  These  configuration  files  are: 

►  ARS.INI 

►  ARS.CFG 

►  ARS. CACHE 

►  ARS. DBFS 

ARS.INI 

This  file  contains  a  section  for  each  instance;  each  section  begins  with  a  header. 
It  is  created  at  installation  time  and  by  default,  is  configured  with  information  for 
the  archive  instance.  To  update  the  file,  simply  copy  the  archi  ve  section  to  a 
new  section  and  update  the  newly  copied  section  for  the  new  instance. 

Figure  4-1  shows  a  sample  ARS.INI  file  for  our  scenario. 
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[@SRV@_ARCHIVE] 

H0ST=9 .17 . 64 .210 
PROTOCOL=2 
PORT=14  50 

SRVR_INSTANCE=ARCHIVE 
SRVR_INSTAWCE_OWNER=root 
SRVR_OD_CFG=/usr/lpp/ars/conf ig/ars . cf g 
SRVR_DB_CFG=/usr/lpp/ars/conf ig/ars . dbf s 
SRVR_SM_CFG=/usr/lpp/ars/conf ig/ars .cache 

[@SRV@_ondtest] 

HOST=9 .17 . 64 .210 

PROTOCOL=2 

PORT=1441 

SRVR_INSTANCE=ondtest 

SRVR_INSTANCE_OWNER=root 

SRVR_OD_CFG=/usr/lpp/ars/config/ars_ondtest.cfg 
SRVR_DB_CFG=/usr/lpp/ars/conf ig/ars_ondtest . dbf s 
SRVR_SM_CFG=/usr/lpp/ars/config/ars_ondtest. cache _ 

Figure  4- 1  ARS.INI  file  sample 

Notice  that  we  created  a  new  section  called  ondtest,  the  name  of  our  new 
instance.  Each  instance  should  point  to  the  HOST  name  or  IP  address  of  a 
physical  server.  OnDemand  differentiates  instances  by  the  PORT  number.  This 
parameter  identifies  the  TCP/IP  port  that  OnDemand  monitors  for  client  requests; 
each  instance  must  use  a  unique  and  unused  port.  The  default  port  is  0,  which 
points  to  port  1445.  You  must  choose  a  different  value  for  each  additional 
instance.  We  chose  an  unused  port  of  1441 . 

The  next  parameter  that  must  be  changed  is  the  SRVR_INSTANCE  parameter. 
This  specifies  the  name  of  the  database  OnDemand  used.  In  our  scenario,  it  is 
ondtest.  Again,  we  recommend  that  the  instance  name  and  the  database  name 
to  be  the  same.  The  SRVR_INSTANCE_OWNER  parameter  must  be  the  user  ID 
that  owns  the  instance.  We  recommend  that  this  be  root,  but  it  is  not  mandatory. 

Finally,  we  must  specify  the  location  of  the  server  configuration  file,  the 
tablespace  file  system  and  the  cache  file  system  for  each  instance.  The  final 
three  parameters  in  the  instance  section  point  to  these  configuration  files. 


58 


Content  Manager  OnDemand  Guide 


Note:  You  must  ensure  that  the  ARS.INI  file  is  consistent  across  all  servers 
that  are  part  of  the  OnDemand  system.  If  you  make  an  update  to  the  ARS.INI 
file  on  the  library  server,  you  must  make  the  appropriate  update  to  the  ARS.INI 
files  on  the  object  server(s)  if  they  do  not  reside  on  the  same  machines. 


ARS.CFG 

When  an  instance  is  started,  OnDemand  reads  the  ARS.INI  file  to  determine 
where  the  server  configuration  file  is  located.  Each  instance  must  have  its  own 
ARS.CFG  file  that  is  determined  by  the  ARS_0D_CFG  parameter  in  ARS.INI.  Copy  the 
original  ARS.CFG  file  and  modify  it  appropriately.  For  our  scenario,  we  created  a 
file  named  ars_ondtest.cfg. 

Most  of  the  parameters  are  same  for  the  multiple  instances.  The  only  parameters 
that  must  be  changed  are  the  database-related  ones.  You  need  to  change  your 
DB2 INSTANCE  parameter  to  your  new  name,  and  you  need  to  change  the  database 
path,  the  primary  and  the  archive  log  file  directories.  We  recommend  that  each 
database  resides  in  its  own  unique  file  directory. 

The  ARS_DB2_DATABASE_PATFI  variable  defines  the  base  file  system  in  which  the 
OnDemand  database  will  reside.  The  default  is  /arsdb.  In  our  scenario,  we 
created  a  file  system  called  /ondtest/arsdb  to  hold  our  database. 

The  ARS_DB2_PRIMARY_L0GPATH  and  ARS_DB2_ARCHI  VE_LOGPATH  parameters  define 
the  active  and  offline  archive  log  files,  respectively.  These  directories  should  also 
be  unique  for  each  instance. 

The  group  that  the  database  instance  owner  belongs  to  must  have  write  access 
to  the  database  directories  specified  here.  The  database  instance  owner  is  the 
user  ID  that  you  specified  when  you  created  the  instance.  Verify  that  the  entire 
database  tree  (/ondtest/arsdb*  in  our  scenario)  is  in  the  sysadml  group. 


Note:  We  strongly  recommend  that  each  instance  uses  a  different  set  of  TSM 
options  files. 


Figure  4-2  shows  the  updated  sections  of  ARS_ONDTEST.CFG  for  our  scenario. 
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######################################## 

#  DB2  Parameters  (Library  Server  Only)  # 
######################################## 

# 

DB2lNSTANCE=ondtest 

# 

ARS_DB2_DATABASE_PATH=/ondtes  t/arsdb 
ARS_DB2_PRIMARY_L0GPATH=/ondtest/arsdb_primarylog 
ARS_DB2_ARCHIVE_L0GPATH=/ondtes  t/arsdb_archi velog 
ARS_DB2_L0GFILE_SIZE=1 000 
ARS_DB2_LOG_NUMBER=2  0 
# 

Figure  4-2  ARS_ONDTEST.CFG  file  sample 

ARS. CACHE 

OnDemand  supports  cache  storage  for  temporary  storage  and  high-speed 
retrieval  of  reports  that  are  stored  on  the  system.  Each  OnDemand  instance 
should  have  its  own  cache  storage;  this  allows  for  a  complete  differentiation 
between  the  instances.  The  SRVR_SM_CFG  parameter  in  the  ARS.  INI  file  identifies 
the  unique  cache  file  system  used  by  the  instance.  This  file  can  contain  one  or 
more  file  systems. 


Important:  The  first  line  in  the  ARS .  CACHE  file  identifies  the  base  cache  storage 
file  system  where  OnDemand  stores  the  control  information.  After  you  define 
this  value,  you  cannot  add  or  remove  it  from  OnDemand  or  change  it  in  any 
way. 


The  permissions  on  these  file  systems  are  very  important.  On  AIX  servers,  the 
cache  file  system  must  be  owned  by  the  root  user  and  the  system  group.  On 
HP-UX  and  Sun  Solaris,  these  file  systems  must  be  owned  by  the  root  use  and 
the  root  group.  You  must  ensure  no  other  permissions  are  set.  On  AIX,  the  file 
system  permissions  should  be  similar  to  those  shown  in  Figure  4-3. 


Figure  4-3  Cache  file  system  permissions 

ARS. DBFS 

The  ARS. DBFS  file  is  called  from  the  ARS.  INI  file  at  the  instance  startup.  The 
ARS. DBFS  contains  the  file  names  in  which  OnDemand  can  store  tablespace  and 
it  determines  the  type  of  tablespace  that  OnDemand  can  create.  Storing 
application  group  index  data  in  tablespace  is  optional,  but  highly  recommended. 
We  also  recommend  that  these  file  systems  contain  only  OnDemand  data,  and 
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that  each  instance  on  the  server  has  its  own  file  systems  on  which  to  store  data. 
In  general,  the  more  tablespace  file  systems  that  are  defined,  the  better  the 
system  performance.  When  using  more  than  one,  each  of  these  file  systems 
should  have  the  same  allocated  disk  space. 

When  using  DB2  as  the  database,  OnDemand  supports  the  use  of  SMS 
tablespace.  Using  SMS  allows  the  operating  system  to  increase  the  size  of  the 
tablespace,  as  required,  during  a  load  process. 

When  creating  a  new  instance  that  uses  tablespace,  you  must  create  a  new 
ARS.DBFS  file.  We  created  ars_ondtest.dbfs  in  our  scenario.  Each  line  in  this  file 
must  contain  the  name  of  the  file  system  and  the  type  of  tablespace  to  be  stored. 
These  file  systems  must  be  owned  by  the  database  instance  owner  and  the 
group.  In  our  scenario,  it  is  owned  by  ondtest  and  belongs  to  the  sysadml  group. 
See  Figure  4-4  for  the  correct  permissions.  We  include  the  word  SMS  in  the  file 
system  name  to  indicate  what  type  of  data  will  be  stored. 


Figure  4-4  SMS  tablespace  permissions 

Create  OnDemand  database 

Once  the  database  instance  is  created,  and  all  the  OnDemand  directories  are  set 
up  with  the  appropriate  permissions,  it  is  time  to  create  the  OnDemand  database. 
Verify  that  the  group  that  the  database  instance  owner  (ondtest)  belongs  to  has 
the  write  access  to  the  database  directory  names  specified  in  the  ARS.CFG  file. 

The  arsdb  command  performs  the  following  actions: 

►  Updates  the  database  configuration 

►  Verifies  the  directories  for  the  primary  and  the  archived  log  files 

►  Creates  a  link  to  the  database  user  exit  program 

►  Creates  a  backup  of  the  database 

►  Builds  the  OnDemand  system  tables  and  indexes 

►  Binds  the  database  to  OnDemand 

Sign  on  to  the  user  account  that  you  assigned  as  the  owner  of  the  OnDemand 
instance  (in  the  ARS.  INI  file).  In  our  scenario,  this  is  root.  Run  the  arsdb 
command  with  the  following  options: 

arsdb  -I  ondtest  -gcv  (where -I  is  the  OnDemand  instance) 
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After  this  command  completes,  you  should  be  able  to  log  into  DB2  and  connect 
to  the  new  instance.  If  you  list  all  the  tables  (by  typing  db2  list  tables  for  all), 
you  should  see  the  new  ARS  tables,  owned  by  root.  If  this  command  fails  for  any 
reason,  it  will  create  db2uexi  t .  err  file  in  the  ARS_TMP  directory  specified  in  the 
ARS.  INI  file;  by  default,  it  is  /tmp. 

Initialize  System  Log  and  migration  facility 

After  you  have  successfully  created  the  database,  you  can  initialize  the  system 
log.  To  do  so,  enter  the  following  command: 

arssyscr  -I  ondtest  -1  (where  -I  is  the  new  OnDemand  instance) 

You  must  also  initialize  the  system  migration  facility.  To  do  so,  enter  the  following 
command: 

arssyscr  -I  ondtest  -m  (where -I  is  the  new  OnDemand  instance) 

The  arssyscr  program  creates  the  application  groups,  applications,  and  folders 
required  by  the  system  logging  and  system  migration  facilities. 


Note:  The  arsdb  and  arssyscr  commands  are  located  in  /usr/1  pp/ ars/bi  n  in 
AIX  and  /opt/ondemand/bi  n  in  HP-UX  and  Sun  Solaris. 


4.2.2  Working  with  the  second  instance 

This  section  describes  how  to  work  with  the  second  instance. 

Starting  and  stopping  arssockd 

Congratulations,  you  are  now  ready  to  start  up  the  new  instance!  Start  the  new 
instance  the  same  way  you  would  the  original,  but  add  the  instance  name  after 
the  arssockd  command,  as  follows: 

arssockd  ondtest 

Use  the  ps  command  to  verify  that  the  instance  is  started: 

ps  -ef  |  grep  ars 

If  you  have  more  than  one  instance  running,  you  will  see  more  than  one  arssockd 
process  in  the  accepting  state.  The  new  instance  has  a  -instancename  after  it  to 
identify  it.  The  original  instance  (or  archive  instance),  has  no  instance  name.  Be 
sure  that  when  you  stop  the  instance,  you  are  stopping  the  correct  one.  Stop  the 
instance  in  the  same  manner  as  you  normally  do:  Issue  a  kill  command  on  the 
accepting  process. 
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Connecting  to  instances 

To  connect  to  a  particular  instance,  the  client  must  log  on  to  the  correct  library 
server.  Add  a  new  server  in  the  administrative  or  user  client  by  identifying  the 
name  of  the  library  server  and  the  port  number  to  use.  The  port  number  you 
specify  must  be  the  same  port  number  that  you  specified  in  the  ARS.  INI  file. 

Running  commands 

In  general,  the  -h  or  -i  parameters  are  used  to  determine  the  name  of  the 
OnDemand  instance  to  process.  You  must  specify  the  parameter  and  the 
instance  name  if: 

►  The  name  of  the  default  instance  is  not  ARCHIVE. 

►  You  are  running  more  than  one  instance  on  the  same  system  and  you  want  to 
process  an  instance  other  than  the  default  instance. 

►  You  are  running  the  program  on  a  system  other  than  where  the  library  server 
is  running. 

The  programs  locate  the  specified  instance  name  in  the  ARS.  INI  file  to  determine 
the  TCP/IP  address,  host  name  alias,  or  fully-qualified  host  name  of  the  system 
on  which  the  OnDemand  library  server  is  running  and  other  information  about  the 
instance.  The  ARSADM,  ARSADMIN,  ARSDOC,  and  ARSLOAD  programs  support  the  -h 
parameter.  The  ARSDB,  ARSLOAD  ARSMAINT  and  ARSTBLSP  programs  support  the  -  I 
parameter.  For  the  ARSLOAD  program,  if  both  the  -h  and  -I  parameters  are 
specified,  the  value  of  the  last  parameter  specified  is  used.  For  example: 

arsload  -g  appl icationgroup  -u  admin  -p  ondemand  -I  ondtest  test. data 

arsmaint  -cmsv  -I  ondtest 


4.3  Multiple  instances  on  Windows  NT 

In  this  section,  we  describe  how  to  define  a  second  instance  on  Windows  NT 
environment. 

4.3.1  Defining  a  second  instance 

Connect  to  the  library  server  in  the  OnDemand  configurator  and  select  File  -> 
New  Instance.  Notice  that  you  must  highlight  an  existing  instance  in  order  for  this 
option  to  show.  Select  a  meaningful  name  for  the  new  instance. 

On  the  next  screen,  the  server  screen,  click  communications.  Choose  a  port  for 
the  OnDemand  clients  to  use  to  communicate  with  the  server.  You  must  choose  a 
unique  port  for  each  new  instance.  The  default  is  0,  which  defaults  to  1 445.  If  you 
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do  not  change  this  port,  you  will  not  get  an  error  message;  instead,  every  client 
trying  to  access  the  original,  archive  instance,  through  port  1445  will  now  be 
trying  to  log  into  this  new  instance  instead.  You  will  not  be  able  to  access  the 
original  instance  until  you  change  this  port  to  a  unique  number. 

We  recommend  that  you  define  unique  file  systems  for  each  instance  as  you 
define  the  file  systems  to  control  this  instance  (cache,  temp,  and  database 
directories).  This  is  a  way  to  keep  the  instance  data  and  indexes  separate  from 
one  another.  You  must  assign  a  unique  database  directory,  primary  and  archive 
log  file  directories,  or  you  will  get  an  error  when  creating  the  database. 

Once  you  have  finished  defining  the  instance,  you  may  click  Create  Database 
Now  to  create  the  DB2  tables.  This  will  create  the  ARS  Db2  tables,  and  will 
initialize  the  system  log  and  migration  facility.  You  may  also  choose  to  run  these 
commands  manually  by  running  the  arsdb  command  or  the  arssyscr  commands 
with  the  -  I  parameter. 


Note:  There  are  now  additional  services.  There  is  a  new  library  server,  MVS 
download  server  and  load  data  server,  for  the  new  instance. 


Refer  to  4.2.2,  “Working  with  the  second  instance”  on  page  62  for  instructions  on 
how  to  connect  to  the  new  instance  and  how  to  run  the  OnDemand  programs. 


4.4  Multiple  instances  on  iSeries 

An  OnDemand  for  iSeries  instance  is  a  logical  server  environment  consisting  of  a 
server  and  its  own  separate  database  and  disk  space.  An  instance  is  defined  in 
the  ars .ini  file. 

Each  OnDemand  for  iSeries  instance: 

►  Has  its  own  set  of  application  groups,  applications,  folders,  and  printers 

►  Has  its  own  security  settings  for  users,  groups,  application  groups,  and  folders 

►  Has  its  own  system  log 

►  Must  run  in  a  Single  Coded  Character  Set  ID 

A  second  iSeries  instance  can  be  created  to  enable  a  separate  test  environment 
or  to  physically  separate  data  from  two  different  sources.  We  recommend  that  the 
default  instance  name  QUSROND  be  used  for  the  first  instance. 
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Note:  Most  OnDemand  commands,  such  as  ADDRPTOND  and  STRMONOND,  default 
to  the  QUSROND  instance  name.  If  other  instances  are  created,  the  name  of  the 
instance  will  need  to  be  included  in  any  OnDemand  system  commands  which 
are  instance  specific. 


When  creating  a  second  instance  in  OnDemand  for  iSeries,  a  name  needs  to  be 
chosen  that  is  a  unique  and  valid  library  name  for  OS/400.  No  other  library  by 
that  name  can  exist.  The  name  cannot  start  with  the  letter  Q  and  cannot  be 
confi g,  CONFIG,  www  or  WWW. 

Here  are  the  steps  to  follow  when  creating  a  second  instance: 

1 .  Log  on  to  the  iSeries  using  the  CCSID  to  be  used  to  load  data  into  the 
instance  and  issue  the  following  command: 

CALL  QRDARS/QRLMINST  PARM(REDB00K  ENU) 

REDBOOK  is  the  name  of  the  new  instance  and  will  be  used  in  the  rest  of  the 
examples  here.  ENU  is  the  US  English  language.  Running  this  command  to  set 
up  the  second  instance: 

-  Appends  the  information  required  for  the  new  instance  into  the  ARS.  INI  in 
the  /QIBM/UserData/OnDemand/CONFIG  directory 

-  Creates  the  new  instance  directory  under  /QIBM/UserData/OnDemand 

-  Creates  the  ARS. CFG,  ARS. CACHE,  and  ARS. DBFS  files 

-  Creates  the  library  and  database  tables  for  the  new  instance 

-  Creates  the  directories  needed  by  the  new  instance  as  specified  in  the 
ARS. CFG  and  the  ARS. CACHE  files 

As  the  command  runs,  you  will  see  messages  for  the  database  table 
creations  and  other  function  which  are  being  performed.  There  will  be  a 
completion  message  stating  that  the  new  OnDemand  instance  has  been 
instantiated. 

2.  Edit  the  ARS.  INI  file  (Figure  4-5  on  page  66)  using  the  following  command: 

WRKLNK  ‘/QIBM/UserData/OnDemand/CONFIG/ARS. INI ’ 

Page  down  until  you  find  the  section  that  was  inserted  into  the  ARS.  INI  file  for 
the  new  instance  that  was  created.  The  port  number  will  need  to  be  changed 
to  a  port  that  is  not  already  in  use  by  another  instance.  By  default,  a  port 
number  of  0  is  used  for  new  instances.  This  will  cause  OnDemand  to  attempt 
to  use  the  default  port  number  of  1445  which  may  already  be  in  use  by  the 
QUSROND  default  instance. 
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3.  If  you  do  not  want  to  use  OS/400  security  for  the  new  instance,  change  the 
security  setting  to  0  by  modify  the  following  line  in  the  ARS.  INI  file 
(Figure  4-5). 

SRVR_FLAGS_SECURITY_EXIT=0 

The  default  setting  of  1  causes  the  OS/400  security  to  be  used  for  the 
instance.  By  choosing  not  to  use  the  OS/400  security,  every  OnDemand  user 
does  not  need  an  OS/400  ID.  The  user  only  needs  an  OnDemand  user  ID. 


Figure  4-5  ARS.INI  file  sample  for  iSeries 


4.  Edit  the  ARS. CFG  file  (Figure  4-6)  using  the  following  command: 

WRKLNK  ‘/QIBM/UserData/OnDemand/REDBOOK/ARS.CFG’ 

If  the  new  instance  will  start  automatically  when  the  STRTCPSVR  command  is 
issued,  change  the  ARS_AUTOSTART_INSTANCE  parameter  from  0  to  1. 
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Note:  The  ARS.  INI  and  ARS.CFG  files  may  also  be  edited  by  mapping  a  drive  to 
the  iSeries  Integrated  File  System  root  directory  using  Windows  Explorer. 
Open  the  file  in  an  editor  such  as  Notepad  or  Wordpad,  make  the  desired 
changes,  and  save  the  file. 


Figure  4-6  ARS.CFG  file  sample  for  iSeries 

5.  Start  the  OnDemand  servers  using  the  following  command: 

STRTCPSVR  *0NDMD 

If  you  want  to  start  only  the  server  for  the  new  instance,  issue  the  following 
command: 

Call  QRDARS/QRLMCTL  *STRTCPSVRREDBOOK 
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You  can  confirm  that  the  REDBOOK  instance  is  started  by  running  the  command: 

WRKACTJOB  JOB(REDBOOK) 

The  job  REDBOOK  will  be  running  program  ARSSOCKD  which  is  the  OnDemand 
library  server  program. 

6.  Verify  that  the  instance  is  functioning  correctly  by  accessing  the  instance  with 
the  OnDemand  client.  Configure  a  connection  to  the  instance  in  the 
OnDemand  client  (Figure  4-7)  using  the  host  name  or  the  IP  address  of  the 
iSeries  along  with  the  port  number  that  you  assigned  to  the  instance. 

User  ID  QONDADM  is  created  during  instance  creation.  The  default  password  for 
this  user  is  qondadml.  If  the  password  has  been  changed  for  use  with  another 
instance,  you  need  to  use  that  password.  Log  on  to  the  server  using  this  ID 
and  the  password. 

The  system  log  and  system  migration  application  groups,  applications,  and 
folders  are  created  when  the  instance  is  created.  Select  the  system  log  and 
run  a  query  for  the  current  day’s  activity.  If  you  can  successfully  view  the  log 
entries,  the  instance  is  set  up  and  communicating  correctly. 


Figure  4-7  Client  server  set  up  for  iSeries 
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4.5  Multiple  instances  on  z/OS 

Instances  on  z/OS  do  not  differ  greatly  from  those  on  multiplatforms.  The  concept 
is  the  same.  In  this  section  we  explain  how  to  set  up  a  new  instance  and  provide 
some  background  information  on  the  USS  implementation. 

Instances  are  logical  implementations  for  the  separation  of  administration 
functions,  users,  and  data  on  the  same  server.  Instances  are  used  to  have  the 
same  physical  access  to  the  program  libraries,  but  they  have  different  databases 
with  a  separate  system  log  and  separate  file  systems.  Instances  are  typically 
used  to  separate  different  customers  on  one  z/OS  server,  to  separate  the  test 
and  production  environments,  or  to  use  different  code  pages  on  different 
databases. 

An  OnDemand  instance  on  a  z/OS  server  is  a  separately  started  task  (ARSSOCKX) 
using  different  databases,  users,  and  application  groups.  Every  user  on  the 
instance  must  be  defined  for  the  instance.  Every  instance  has  its  own  security  as 
long  as  internal  security  is  used.  If  an  external  security  exit  is  used,  it  is  common 
over  all  the  instances.  Figure  4-8  shows  an  overview  of  the  instances  on  z/OS. 


Instances  on  z/OS 


Figure  4-8  Multiple  instances  overview  on  z/OS 
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Each  additional  instance  requires  additional  system  resources  such  as  main 
storage,  virtual  storage,  and  disk  space.  The  administration  effort  increases  with 
every  additional  instance.  The  ars.ini  must  be  consistent  and  maintained 
correctly  for  all  instances.  Before  you  update  the  ars  .ini,  you  should  make  a 
copy  of  the  file. 

In  UNIX  System  Services,  there  are  many  ways  to  create  a  copy  of  a  file. 
Sometimes,  there  are  problems  with  authorization.  If  you  are  a  superuser 
(you  can  verify  this  by  typing  su  on  the  Open  OMVS  shell),  you  can  call  your 
systems  programmer  and  RACF  administrator  to  get  the  right  permissions.  Once 
you  are  in  the  OMVS  shell,  you  can  make  a  backup  copy  of  any  file  by  using  the 
copy  command.  The  following  copy  options  are  available: 

►  Copy  one  file  to  another  file  in  the  working  directory 

►  Copy  one  file  to  a  new  file  in  the  working  directory 

►  Copy  a  set  of  directories  and  files  to  another  place  in  your  file  system 

►  Copy  a  UNIX  file  to  an  MVS  data  set 

►  Copy  an  MVS  data  set  to  a  file  system 

►  Copy  an  MVS  data  set  to  an  MVS  data  set 

Note:  Usually  it  is  sufficient  to  simply  use  the  following  command  from  the 
OMVS  command  line: 

cp  ars.ini  /u/ussdflt/arsini .back 

Here,  /u/ussdf  1 1/  is  the  directory  for  the  copied  dataset.  It  can  be  any 
directory  with  write  permissions. 

For  more  information  on  any  USS  command,  refer  to  UNIX  System  Services 
Command  Reference,  SC28-1892. 


Once  the  dataset  is  copied,  the  ars .  i  ni  file  can  be  updated. 


4.5.1  Understanding  file  systems  in  UNIX  System  Services  (USS) 

Before  we  go  any  further  with  the  creation  of  instances  on  a  z/OS  system,  we  first 
introduce  the  USS  file  system  on  a  z/OS  system.  For  an  MVS  system,  the  file 
hierarchy  in  USS  is  a  collection  of  Hierarchical  File  System  (HFS)  datasets.  Each 
HFS  dataset  is  one  file  system,  and  is  called  a  mountable  file  system  because 
you  can  mount  and  demount  it.  A  file  system  is  created  with  the  ISPF  3.2  allocate 
function  or  with  a  batch  job.  Figure  4-9  lists  the  JCL  that  is  used  to  create  an  HFS 
file. 
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//ALLOCHFS 

(????, ????) , ' HENRY  MARTENS ’ , MSGCLASS=0, CLASS=A, 

// 

N0TIFY=TEAM5, REG  1 0N=64M 

//*  ALLOCATE  HFS  FILE 

//ALLOC 

EXEC  PGM= I EFBR14 

//HFSCA1 

DD  DSN=TEAM5. V710. DBSRES. SERVER, CACHE1. HFS, 

// 

DISP=  (NEW, CATLG, DELETE), 

// 

DSNTYPE=HFS, DCB=  (DS0RG=P0) , 

// 

SPACE=  (CYL,  100,1,1  ), 

// 

UN I T=SYSD A 

//* 

Figure  4-9  JCL  used  to  allocate  an  HFS  file  in  z/OS 


Another  important  point  on  USS  concerns  the  UNIX  permission  bits  for  files  in  an 
HFS.  Any  information  about  a  file  is  stored  with  the  file  in  the  file  system.  In  a 
z/OS  environment,  this  information,  such  as  file  size  and  creator,  are  stored  in  a 
user  catalog  or  VTOC.  In  a  UNIX  system,  all  files  have  three  type  of  permissions: 

1 .  Read  (displayed  as  r) 

2.  Write  (displayed  as  w) 

3.  Execute  (display  as  x) 

Every  permission  for  a  UNIX  file  (read,  write,  and  execute  —  rwx)  is  maintained 
for  three  different  types  of  file  users: 

1.  The  file  owner 

2.  The  group  that  owns  the  file 

3.  All  other  users 

UNIX  files 

To  find  out  the  permissions  for  a  file,  use  the  1  s  -1  command  from  the  command 
line  of  the  OMVS  shell.  You  will  get  the  following  information  returned  (see 
Example  4-1). 

Example  4-1  UNIX  file  listing 
$  Is  -1  ars.ini 

-rwxrwxrwx  1  SYSADM1  USERID  203  Jun  28  14:02  ars.ini 

$ 
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In  this  case,  the  list  file  and  directory  attributes  command  is  used  for  the  ars.  ini 
file  (similar  to  a  dir  filename  command  in  Windows).  The  -1  parameter  gives 
you  more  detailed  information  on  the  file. 


The  result  in  this  example  has  the  following  meaning: 
-nrwxrwxrwx  Permission  bits 

1  Number  of  links  to  the  dataset 

SYSADM1  Name  of  the  file  owner 

USERID  Group  that  owns  the  file 

203  Size  of  the  file  in  bytes 

Jun  28  14:02  Date  and  time  the  file  was  last  changed 

ars. ini  Name  of  the  file 


Note:  This  example  is  taken  from  the  redbook,  OS/390  UNIX  System  Services 
Implementation  and  Customization,  SG24-5178.  This  book  is  a  very  good 
reference  if  you  are  starting  with  UNIX  System  Services. 

Permission  bit  structure 

The  structure  of  this  ten-character  field  is: 


tfffgggooo 

Here,  the  meaning  of  the  permission  byte,  t,  is  shown  in  Table  4-1 . 
Table  4-1  Permission  byte  information 


f 

The  type  of  file  or  directory 

- 

File 

c 

Character  special  file 

d 

Directory 

1 

Symbolic  link 

P 

FIFO  special  file 

e 

OS/390  LOAD  Module 
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fff  stands  for  OWNER  permissions,  ggg  stands  for  the  GROUP  permissions,  and 
ooo  stands  for  the  OTHER  permissions 

HFS  file  data  is  byte-oriented,  which  differs  from  the  MVS  record-oriented 
datasets.  The  I/O  is  done  by  the  use  of  data  stream  and  not  by  writing  records  to 
it.  A  USS  file  system  on  z/OS  looks  similar  to  a  Windows  file  system,  except  for 
the  direction  of  the  slashes.  OnDemand  expects  certain  files  to  be  in  a  specific 
directory.  In  USS,  the  root  file  system  is  the  first  file  system  which  is  mounted. 
You  do  not  add  application  data  to  this  file  system. 

The  path  for  the  OnDemand  system  is  /usr/1  pp/ars/.  From  the  ars  directory, 
there  are  several  directories  which  contain  the  OnDemand  files  and  executable 
files,  such  as  programs  and  procedures.  The  directories  are  created  at  the 
installation  time  when  running  the  ARSMKDIR  REXX  routine  from  the  install  library, 
ODADMIN .  V7R1M0 .  SARINST.  The  /usr/1  pp/ars/  directory  contains  the 
subdirectories  listed  in  Table  4-2. 


Table  4-2  Subdirectories  of  /usr/1  pp/ars 


directory 

contains 

bin 

Contains  all  executables,  such  as  arsdb  for  creating  the  database 

config 

Contains  all  configuration  datasets,  such  as  ars.iri 

locale 

Contains  all  subdirectories  for  NLS 

samples 

Contains  all  sample  files  for  updating 

WWW 

Contains  all  subdirectories  for  ODWEK 
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Figure  4-10  shows  the  OnDemand  HFS  file  structure  in  UNIX  System  Services. 


Figure  4-10  OnDemand  file  structure  in  UNIX  System  Services 


Important:  All  path  parameter  and  commands  are  case  sensitive. 


Sometimes  when  choosing  a  directory  such  as  /usr/1  pp/ars/bi  n ,  you  will  see  a 
different  path  when  you  issue  the  pwd  command.  This  is  because  a  symbolic  link 
is  set.  A  symbolic  link  is  a  file  that  contains  the  path  name  for  another  file  or 
directory.  Only  the  original  path  name  is  the  real  name.  An  external  link  is  a  type 
of  symbolic  link;  it  links  to  an  object  outside  of  the  FIFS.  Typically,  it  contains  the 
name  of  an  MVS  data  set. 
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4.5.2  Creating  an  instance  on  z/OS 

Now  that  you  have  a  better  understanding  of  the  UNIX  System  Services  file 
structure,  in  this  section  we  describe  how  to  create  an  instance  on  z/OS  system. 

Adding  a  file  system  for  the  new  instance 

Once  a  file  system  has  been  allocated,  it  has  to  be  “connected”  with  the  mount 
command.  The  mount  command  can  be  issued  in  the  shell  or  via  a  TSO  command. 
Figure  4-1 1  shows  this  command  and  its  relationship  to  other  files. 


Figure  4-11  Mount  of  a  file  system 

Creating  the  database  for  the  new  instance 

The  new  instance  uses  its  own  set  of  tables.  A  new  database  must  be  created  for 
this  new  instance.  This  can  be  done  by  the  modification  of  the  ARSDB2  member  in 
ODAMIN. V7R1M0. SARSINST  library  which  is  used  for  the  initial  installation.  Several 
modifications  of  this  job  are  necessary: 

►  Change  the  SQLID  to  another  user  (this  user  must  have  sysadm  authority). 

►  Change  the  Create  Storage  Group  Statement  if  you  want  a  new  storage 
group  for  the  instance  (this  is  optional). 

►  Change  the  Create  Database  Statement. 

►  Run  the  job. 
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Creating  the  tablespace 

The  new  instance  uses  its  own  tables.  A  tablespace  is  needed.  See  3.1 ,  “System 
control  tables”  on  page  42  for  a  detailed  description.  This  can  be  done  by  the 
modification  of  the  ARSTSPAC  member  in  ODAMIN.  V7R1M0.SARSINST  library  which  is 
used  for  the  initial  installation.  Modifications  to  the  job  are  as  follows: 

►  Change  the  SQLID  to  the  same  user  used  for  creation  of  the  database  in 
ARSDB2 . 

►  Change  the  IN  Parameter  of  the  CREATE  TABLESPACE  statement  to  the 
database  name  you  previously  created  in  ARSDB2. 

►  Change  the  USING  parameter  to  the  STOGROUP  name  you  previously  used  in 
ARSDB2. 

►  Set  the  appropriate  values  for  the  primary  and  secondary  allocation. 

►  Run  the  job. 

Creating  a  new  configuration  file 

When  an  instance  is  started,  OnDemand  reads  the  ARS.  INI  file  to  determine 
where  the  server  configuration  file  is  located.  Each  instance  must  have  its  own 
configuration  file  such  as  ARS. CFG  that  is  determined  by  the  ARS_0D_CFG 
parameter  in  ARS.  INI.  Copy  the  original  ARS. CFG  file  and  modify  appropriately. 
Get  the  right  permission  byte  sets.  In  our  scenario,  a  new  configuration  file, 
arsinsl  .cfg  (Figure  4-1 2)  is  created.  The  important  parameters  that  are  database 
related  need  to  be  changed: 

►  ARS_DB_TABLESPACE:  The  name  of  the  tablespace  created  with  the 
ARSTSPAC  member  of  the  installation  library  for  the  new  instance 

►  DB2INSTANCE:  The  name  of  the  database  created  with  the  ARSDB2 
member  of  the  installation  library  for  the  new  instance 

All  other  parameters  remain  the  same,  unless  you  want  to  try  something  else 
with  this  new  instance,  such  as  using  OAM,  or  a  different  language. 
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tl  OnDemand  Parameters,  tt 
ARS_NUM_L ICENSE=10 
tt 

ARS_LANGUAGE=ENU 

ARS_SRVR= 

ARS_LOCAL_SRVR= 
ARS_NUM_DBSRVR=4 
ARS_TMP=/ tmp 
ARS_PRINT_PATH=/tmp 
DB_ENG I NE=DB2 
tttttttttttttttttttttttttttttttttttttt 
tt  DB2  Parameters,  tt 
tttttttttttttttttttttttttttttttttttttt 
ARS_DB_TABLESPACE= ARSTS INI 
DB2INSTANCE=ARSDBAS1 

ARS_NUM_OAMSRVR= 1 
ARS_0AM_DB2SSID= IDB2 
ARS_OAM_PLAN=CBRIDBS 


Figure  4-12  arsinsl.cfg  file  for  the  new  instance  on  z/OS 

Create  a  new  cache  configuration  file 

Every  instance  should  use  its  own  file  system.  Copy  the  ars. cache  file  and 
modify  it  to  be  the  new  instance  cache  configuration  file.  Add  the  formerly 
created  and  mounted  HFS  (in  this  case  /ars/cache3). 

Adding  the  new  instance  to  the  ars. ini  file 

OnDemand  looks  up  into  the  ars. ini  file  (Figure  4-13)  to  find  its  parameter 
values.  There  is  one  entry  for  every  instance  in  the  ars .  i  ni  file.  These  are  the 
parameters  that  must  be  changed: 

►  @SRV@_ARSSOCKT:  The  instance  name 

►  SRVR_INSTANCE:  The  name  of  the  database  created  with  the  ARSDB2 
member  of  the  installation  library 

►  SRVR_INSTANCE_OWNER:  The  name  of  the  SOLID  when  the  database  is 
created  with  the  ARSDB2  member  of  the  installation  library 

►  Port  number:  This  is  unique  and  is  used  by  instances. 

►  SRV_OD_CFG:  The  name  of  the  previously  created  configuration  file 

►  SRV_SM_CFG:  The  name  of  the  cache  configuration  file 
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[ §SRV§_ARSSOCKD ] 

HOST=wscmvs. Washington  .ibm.com 

PR0T0C0L=2 

P0RT=1444 

SRVR_INSTANCE=ARSDBASE 
SRVR_INSTANCE_OWNER=ARSSERVR 
SRVR_OD_CFG=/usr/ 1 pp/ars/con  f ig/ars.  cfg 
SRVR_SM_CFG=/usr/ 1 pp/ars/con  f ig/ars.  cache 
[ §SRV§_ARSSOCKT ] 

HOST=wscmvs. Washington . ibm.  com 

PR0T0C0L=2 

P0RT=1555 

SRVR_INSTANCE=ARSDBAS1 
SRVR_INSTANCE_0WNER=ARSSERV1 
SRVR_OD_CFG=/usr/ 1 pp/ars/con  f ig/ars insl . cfg 
SRVR_SM_CFG=/usr/ 1 pp/ars/con  f ig/ars insl . cache 

Figure  4-13  ars.ini  for  two  instances 


Attention:  The  ars .  i  ni  file  is  very  sensitive  to  what  kind  of  square  brackets 
you  have  used  as  a  delimiter.  Even  if  it  looks  the  same  on  the  Ishell  editor 
when  displaying  them,  it  depends  on  the  code  page  used  by  the  machine,  and 
the  Hex  value  may  not  represent  the  correct  value,  which  can  lead  to 
unpredictable  results. 


Example  4-2  shows  the  correct  Hex  values  for  new  instance  name. 

Example  4-2  Hex  values  for  instance  name 

Y§SRV§_ARSSOCKD  ' 

A7EDE76CDEEDCDCB 

DC295CD19226324D 


Be  sure  that  your  bracket  is  X’BD’ 
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Creating  tables  for  the  new  instance 

After  all  the  DB2  objects  are  created  and  the  configuration  files  are  updated,  the 
database  for  the  instance  (the  system  tables)  must  be  created.  This  is  done  with 
the  ARSDB  program. 


Important:  When  work  with  more  than  one  instance,  you  must  identify  the 
instance  name  when  running  the  OnDemand  programs  such  as  ARSDB, 
ARSLOAD  and  ARSSOCKD,  and  for  executing  database  commands. 


Create  the  tables  by  following  these  steps: 

1.  Go  into  OMVS. 

2.  Switch  to  superuser  (SU). 

3.  Set  the  environment  variable  to  access  the  DB2  on  z/OS. 

export  DSNAOINI=”/etc/ars/cl i .ini” 

The  minimum  parameters  given  are  the  DB2  SSID  and  the  interface  (DSNCLI). 

4.  Issue  the  SET  command  from  the  OMVS  command  line. 

5.  Move  to  the  OnDemand  executable  directory, 
cd  /usr/lpp/ars/bin 

6.  Run  the  ARSDB  program.  This  is  case  sensitive! 

arsdb  -I  ARSSOCKT  -c 

7.  The  ARSDB  program  generates  a  series  of  messages.  It  acknowledges  the 
successful  creation  of  the  tables  when  all  the  tables  are  created  without  any 
error;  otherwise,  it  creates  error  messages. 

If  you  get  a  message  similar  to  the  following: 

arsdb:  “Unable  to  determine  the  database  engine" 

This  may  look  like  an  DB2  error.  Actually,  the  ARSDB  program  cannot  read  the 
configuration  file.  Check  the  log  for  any  RACF  messages  writing  to  or  opening 
the  file  system. 

Many  installations  run  several  DB2  systems  on  the  z/OS  LPAR.  Sometimes,  this 
can  lead  to  errors  if  the  link  list  contains  only  the  DSNLOAD  and  DSNEXIT  library 
from  a  different  DB2  subsystem.  You  can  add  your  requested  DB2  library  with  the 
export  command;  see  Example  4-3. 

Example  4-3  Export  library 

export  STEPLIB=ICCDB2.SDSNEXIT:ICCDB2.SDSNL0AD  This  sets  the  environment. 
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Tip:  If  you  exit  the  shell,  the  setting  is  gone.  You  can  add  the  export 
command  to  your  OMVS  login  profile.  Check  your  variables  with  the  SET 
command. 


Initialize  the  system  log 

After  creating  the  OnDemand  system  tables,  the  system  log  needs  to  be 
initialized  with  the  ARSSYSCR  program  for  this  new  instance: 

1 .  Move  to  the  OnDemand  executable  directory: 
cd  /usr/lpp/ars/bin 

2.  Run  the  ARSSYSCR  program  for  this  instance  by  using  the  -I  parameter: 
arssyscr  -  I  ARSSOCKT  -1 

Here,  ARSSOCKT  is  the  name  of  the  instance. 

Starting  the  new  Instance 

Once  everything  is  set  up,  you  can  start  the  new  instance  by  running  another 
started  task  on  the  z/OS  system.  The  JCL  is  the  same,  except  that  it  tells  the 
started  task  which  instance  to  take,  by  means  of  a  Parm  parameter  in  the  EXEC 
statement: 

Parm=(7 IIIIIIIII  XXXXXXXX) 

In  this  statement: 

►  IIIIIIIII  is  the  instance  name. 

►  XXXXXXXX  is  the  program  name. 
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Figure  4-14  shows  an  example  of  starting  a  second  instance. 


//ARSSOCKT  JOB  (QFTA0000, B123) , 

//  ’Henry  Martens MSGCLASS=0,  01053=0, 

//  N0TIFY=&SYSUID, USER=TEAM5,  TIME=1440 

//ARSSOCKT  PROC 

//ARSSOCKT  EXEC  PGM=ARSS0CKD, PARM= ( ’ /ARSSOCKT  ARSSOCKD’), 

//  REGION=0M, T I ME=N0L I M I T 

//* 

//STEPLIB  DD  DISP=SHRJ  DSN=0D390. V710. DBS. SARSLOAD 
//  DD  DISP=SHRJ  DSN= I CCDB2 . SDSNEXIT 

//  DD  DISP=SHRJ  DSN=ICCDB2, SDSNLOAD 

//DSNAOINI  DD  PATH= ’ /etc/ars/cli . in i ’ 

//SYSPRINT  DD  SYS0UT=* 

//SYSOUT  DD  SYS0UT=* 

Figure  4-14  Starting  a  second  instance 

After  this  procedure  is  started,  you  should  logon  to  the  new  instance  using  the 
different  port  number  and  create  users,  application  groups,  applications,  and 
storage  sets  with  the  normal  procedures. 
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Figure  4-15  provides  an  overview  and  the  relations  between  the  steps  for  the 
creation  of  a  second  instance.  You  can  have  as  many  instances  as  you  want, 
depending  on  the  resources  your  z/OS  system  has. 


$  export  STEPLIB...  DSNALOAD  DSNEXI 
$  export  DSNAOINI=7etc/ars/cli.ini" 


//ARSSOCKT  PROC 

//ARSSOCKT  EXEC  PGM=ARSSOCKD,PARM=(7ARS! 
ARSSOCKD'), 

//  REG  ION=OM,TI  ME=NOLI  MIT 

//* 

//STEPLIB  DD  DISP=SHR,DSN=OD390.V71 0.DBS.SARSLOAD 
//  DD  Dl SP=SH R,DSN=I CCDB2.SDSNEXIT 

//  DD  Dl SP=SH R, DSN=I CCDB2.SDSNLOAD 

//DSNAOINI  DD  PATH=yetc/ars/cli  .ini' 

//SYSPRINT  DD  SYSOUT=* 

//SYSOUT  DD  SYSOUT=* 


ars.mi 


SET  CURRENT  SQLID=ARSSERV1 
CREATE  STOGROUP  ARSSGRP1 
VOLUMES  ('*7*') 

VCAT  OD710 ; 

CREATE  DATABASE  ARSDBAS1 
STOGROUP  ARSSGRP1 ; 

ARSTSPAC 
SET  CURRENT  SQLID='ARSSERV1 
CREATE  TABLESPACE  ARSTSIN1 
IN  ARSDBAS1 

USING  STOGROUP  ARSSGRP1 
PRIQTY  700 
SECQTY  7000 
SEGSIZE  32 
BUFFERPOOL  BP32K; 


Y§SRV§_ARSSOCKD" 

HOST =wscmvs.  washington.ibm.com 

PROTOCOLS 

PORT=1444 

SRVRJ  NST ANCE=ARSDBASE 
SRVR_INSTANCE_OWNER=ARSSERVR 
SRVR_OD_CFG=/usr/lpp/ars/config/ars.cfg 
SRVR_SM_CFG=/usr/lpp/ars/config/ars.cache 
rY§SRV§_AR^SOCKT’ 

HOST =ws0\vs.  washington.ibm.com 

PROTp(X)L=2 

POpf=1555 

RVRJ  NST ANCE=ARSDBAS1 
r  SRVRJ  NSTANCE_OWNER=ARSSERV  1 
SRVR_OD_CFG=/usr/lpp/ars/conf  ig/arsi  ns  1  .cf  g 
SRVR_SM_CFG=/usr/lpp/ars/config/arsins1. cache 


arsinsl  .cfg 


ARS_NUM_LICENSE=1 0 

ARS_LANGUAGE=ENU 

ARS_SRVR= 

ARS_LOCAL_SRVR= 
ARS_NUM_DBSRVR=4 
ARS_TMP=/tmp 
ARS_PRI  NT_PATH=/tmp 
DB_ENGINE=DB2 

1  ARS_DB_TABLESPACE=ARSTSI  N1 
DB2 1  NST ANCE=ARSDBAS  1 


Figure  4-15  Relationship  between  the  steps  for  creating  an  instance  on  z/OS 
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Run  arsload  to  check  the  new  instance  and  the  new  file  system 

After  all  the  configuration  work  is  done  and  the  application  group,  application, 
and  folder  are  created,  use  the  arsload  program  for  an  installation  verification. 
Figure  4-16  shows  the  procedures  used  to  load  data  to  the  new  instance.  If  you 
see  problems  in  loading  the  file  (writing  an  object),  check  the  user  permissions. 

//ARSL0AD1  JOB  (QFTA0O00, B123) , 

//  ’Henry  Martens MSGCLASS=0, CLASS=UJ 

//  NOTIFY=&SYSUID, USER=SYSADM1 

//STEP1  EXEC  PGM=ARSLOADJ  REGION=0M, 

//  PARM=(’/  -u  Henry  -p  xxxxxxxx  -n  -f  -I  ARSSOCKT 
//  -g  American  /dev/nuU’) 

//*  -I  ARSSOCKD  -g  CKL1  /dew/nulD 

//STEPLIB  DD  DISP=SHR, DSN=OD390. V710. DBS, SARSLOAD 

//  DD  DISP=SHR, DSN=ICCDB2. SDSNEXIT 

//  DD  DISP=SHR, DSN=ICCDB2. SDSNLOAD 

//  DD  DISP=SHR, DSN=OD390. V710. ACIF. V2R2M0. SAPKM0D1 

//SYSPRINT  DD  SYS0UT=* 

//SYSABEND  DD  SYS0UT=* 

//SYSOUT  DD  SYS0UT=* 

//INPUT  DD  DISP=0LD, DSN=TEAM5. AMERICAN. DATABIN 

Figure  4-16  ARSLOAD  for  new  instance 
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Storage  management 


In  this  chapter,  we  explore  storage  management  on  various  OnDemand 
platforms.  OnDemand  uses  a  cache  storage  manager  for  disk  storage  and 
supports  the  use  of  archive  storage  managers  to  keep  long  term  copies  of  data 
on  archive  storage  media.  We  consider  the  setup  and  integration  of  OnDemand 
with  the  Archive  Storage  Manager. 

This  chapter  covers  OnDemand’s  interfaces  with: 

►  Tivoli  Storage  Manager  for  Multiplatforms 

►  Object  Access  Method  and  Virtual  Storage  Access  Method  for  OS/390 

►  Archive  Storage  Manager  for  iSeries 


©  Copyright  IBM  Corp.  2003.  All  rights  reserved. 
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5.1  Tivoli  Storage  Manager  for  Multiplatforms 

OnDemand  for  Multiplatforms  has  a  cache  storage  manager  that  is  used  to 
maintain  documents  on  disk  storage.  The  cache  storage  manager  uses  a  list  of 
file  systems  to  determine  the  devices  available  for  storing  and  maintaining 
documents.  Typically,  each  OnDemand  object  server  in  the  system  has  a  defined 
set  of  cache  storage  devices  on  which  the  report  data  can  be  maintained  for  a 
period  of  time  in  order  to  provide  the  fastest  access  times  for  system  users. 
Documents  migrate  from  cache  storage  to  archive  storage  based  on  the 
migration  policy  that  is  defined  for  the  application  group. 

OnDemand  for  Multiplatforms  also  has  an  archive  storage  manager  that  is  used 
to  store  documents  on  archive  media.  The  archive  storage  manager  maintains 
one  or  more  copies  of  documents  and  acts  as  the  interface  between  the  object 
server  and  archive  storage  media.  Tivoli  Storage  Manager  (TSM)  is  provided  with 
OnDemand  as  the  archive  storage  manager.  Documents  can  be  archived  on  a 
variety  of  media  such  as  disk,  optical,  and  tape. The  archive  storage  devices  must 
be  configured  and  defined  to  TSM. 

To  store  application  group  data  to  archive  media,  you  must  assign  the  application 
group  to  a  storage  set  that  contains  a  storage  node  which  is  managed  by  the 
archive  storage  manager.  In  an  application  group  definition.  You  can  specify  that 
the  data  will  be  migrated  to  archive  storage  when  document  is  originally  loaded 
into  the  system,  the  next  time  that  the  migration  maintenance  process  is  run,  or 
after  a  certain  number  of  days  have  passed. 

In  this  section,  we  consider  the  steps  that  need  to  be  followed  in  order  to  set  up 
and  configure  TSM  as  the  archive  manager  for  an  OnDemand  for  Multiplatforms 
system.  This  is  not  meant  to  be  an  exhaustive  coverage  of  TSM,  but  rather  an 
overview  with  emphasis  on  the  parts  of  the  process  that  most  directly  affect  the 
OnDemand  to  TSM  interface. 


5.1.1  TSM  overview 

Before  we  get  started  with  the  installation  process,  we  discuss  a  few  of  the 
components  that  make  up  a  TSM  system.  For  a  more  complete  description  of 
TSM,  refer  to  Tivoli  Storage  Manager  for  Windows  Administrator’s  Guide, 
GC32-0782. 

Figure  5-1  represents  a  typical  TSM  system.  A  short  description  of  each 
component  follows. 
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Storage  policy 

Storage  policy  consists  of  the  following  items: 


Client  node  Represents  an  object  server  which  has  the  TSM  backup 

archive  server  installed  and  which  has  been  assigned  to  a 
policy  domain 

Policy  domain  Contains  the  policy  set,  management  class,  and  archive 

copy  group  that  is  used  by  the  client  node 


Management  class  Determines  where  data  is  stored  and  how  it  is  managed 
Archive  copy  group  Used  to  copy  data  to  TSM  for  long-term  storage 
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Storage  devices  and  media 

Storage  devices  and  media  consist  of  the  following  items: 

Library  One  or  more  drives  with  similar  media  mounting 

requirements 

Drive  TSM  defined  drive  mechanism  in  an  optical  or 

tape  device 

Device  class  Specifies  the  device  type  and  how  the  device 

manages  media 

Storage  pools  and  volumes  A  named  collection  of  storage  volumes  of  the 

same  media  type  which  is  associated  with  a 
device  class 

TSM  installation 

Next  we  go  through  the  process  to  follow  when  installing  and  configuring  TSM  on 
a  Windows  system  and  then  integrating  it  with  OnDemand.  This  is  not  meant  to 
be  a  comprehensive  coverage  of  TSM;  but  we  point  out  areas  that  are  important 
to  the  interface  with  OnDemand.  We  use  Tivoli  Storage  Manager  for  Windows 
5.1  version  in  this  discussion. 

Refer  to  Tivoli  Storage  Manager  for  Windows  Quick  Start,  GC32-0784,  which  is  a 
good  reference  to  help  with  installing  and  configuring  the  TSM  system.  Follow  the 
steps  listed  for  installing  the  TSM  server,  TSM  licenses,  TSM  backup  archive 
client,  and  TSM  device  driver  in  the  guide.  When  these  installations  are 
complete,  continue  to  the  following  section  covering  the  TSM  configuration. 

TSM  configuration 

This  section  covers  the  standard  configuration.  There  is  also  a  minimal 
configuration  which  lets  you  quickly  initialize  the  TSM  server  and  perform  a  test 
backup  to  evaluate  the  system.  We  recommend  using  the  TSM  wizard  functions 
to  perform  the  initial  configuration  tasks. 

During  the  standard  configuration  process,  there  are  wizards  to  help  you  perform 
the  following  tasks: 

►  Analyze  drive  performance  to  determine  the  best  location  for  the  TSM  server. 

►  Initialize  the  TSM  server. 

►  Apply  TSM  licenses. 

►  Configure  TSM  to  access  storage  devices. 

►  Prepare  media  for  use  by  TSM. 

►  Register  TSM  client  nodes. 

►  Define  schedules  for  the  automation  of  TSM  tasks. 
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The  standard  initial  configuration  does  not  cover  all  TSM  functions,  but  does 
result  in  a  functional  TSM  system  that  can  be  modified  and  enhanced  further. 
The  default  settings  used  by  the  wizards  are  appropriate  in  many  cases. 

Initial  configuration 

After  installing  TSM,  perform  the  following  initial  configuration: 

1 .  Open  the  TSM  management  console  and  expand  the  Tivoli  Storage  Manager 
tree  until  the  local  machine  name  is  displayed. 

2.  Right-click  the  local  machine  name  and  select  Add  a  New  TSM  Server  to 
display  the  initial  configuration  task  list. 

3.  Select  Standard  or  Minimal  configuration.  Refer  to  the  TSM  documentation, 
found  in  the  following  Web  site,  for  information  to  help  you  with  your  decision 
concerning  the  configuration  type: 

http : //www. ti vol i . com/support/publ i c/Prodman/publ i cjnanual s/td/TD_PROD_LIST . html 

4.  Select  a  Standalone  or  Network  configuration: 

-  In  a  stand-alone  environment,  a  TSM  server  and  backup  archive  client  are 
installed  on  the  same  machine.  There  can  be  no  network  connected  TSM 
clients. 

-  In  a  network  environment,  a  TSM  server  is  installed.  The  backup  archive 
client  can  be  optionally  installed  on  the  same  machine.  Network 
connected  clients  can  be  installed  on  remote  machines. 

TSM  performance  configuration 

After  the  initial  configuration,  perform  the  following  for  performance  configuration: 

1.  Estimate: 

-  The  number  of  clients  that  the  TSM  server  supports 

-  The  size  of  files  to  be  stored 

We  recommend  that  you  select  the  option,  “mostly  large  files”,  which  allows 
space  for  files  that  are  generally  larger  than  1  MB. 

2.  TSM  analyzes  the  local  drives  to  determine  the  best  location  for  the  initial 
TSM  database,  recovery  log,  and  disk  storage  pool. 

Server  Initialization 

Perform  the  following  actions  for  server  initialization: 

1 .  Choose  the  directory  path  for  storing  files  unique  to  the  TSM  server  instance. 

2.  Choose  the  directories  for  the  TSM  database,  recovery  log,  and  disk  storage 
pool.  The  analysis  performed  during  the  performance  configuration  step 
results  in  preferred  locations  being  listed  as  the  default. 
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3.  Choose  the  logon  account  and  password  to  be  used  to  start  the  TSM  server 
service  and  choose  whether  the  service  will  be  started  automatically  at 
boot-up,  or  whether  it  will  be  started  manually. 

4.  Choose  an  ID  and  password  for  the  TSM  server. 

After  the  selections  have  been  made  for  server  initialization,  TSM  does  the 
following: 

►  Initializes  the  server  database  and  recovery  log. 

►  Creates  the  database,  recovery  log,  and  disk  storage  pool  initial  volumes. 

►  Creates  a  daily  and  weekly  schedule  which  can  be  used  for  automated  TSM 
functions. 

►  Registers  a  local  administrative  client  with  the  server.  The  client  is  named 
admin  and  the  initial  password  is  admin. 

License 

Select  and  apply  the  number  of  licenses  purchased  for  the  different  features  of 
TSM.  The  base  TSM  license  includes: 

►  One  local  backup  archive  client 

►  An  unlimited  number  of  administrative  clients 

►  Enterprise  administrative  support 

►  Server  to  server  volume  support 

►  Network  communication  support 

The  license  information  provided  is  registered  with  the  TSM  server. 

Device  configuration 

The  device  configuration  wizard  automatically  detects  storage  devices  attached 
to  the  TSM  server  and  is  used  to  select  the  devices  that  you  want  to  use  with 
TSM.  To  define  a  device,  select  its  check  box.  Undetected  or  virtual  devices  can 
be  manually  added.  The  libraries  and  drives  that  you  define  to  TSM  are  available 
to  store  data. 

Client  node  configuration 

Client  node  configuration  allows  you  to  add  and  register  the  client  nodes  to  back 
up  the  data  to  the  server  instance  that  is  being  configured.  When  storage  devices 
were  configured  during  device  configuration,  storage  pools  associated  with  these 
devices  were  automatically  generated  and  are  displayed  here. 

TSM  uses  storage  pools  to  represent  storage  devices.  Different  storage  pools 
are  used  to  route  archive  data  to  different  types  of  storage.  Storage  pools  can  be 
arranged  in  a  hierarchy  (Figure  5-2)  to  allow  data  to  be  migrated  from  one  type  of 
storage  to  another.  For  instance,  you  can  set  up  a  storage  pool  hierarchy  which 
would  store  the  data  on  DASD  and  then  move  to  optical  media,  and  finally  store 
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the  data  on  tape.  The  time  that  the  data  is  stored  in  each  storage  pool  is 
determined  by  the  TSM  policy  domain  associated  with  the  storage  pool. 


Figure  5-2  Storage  pool  hierarchy 

TSM  provides  a  default  storage  pool  named  DISKPOOL  which  represents  DASD 
storage  space  on  the  TSM  server.  Three  other  default  storage  pools, 
ARCHIVEPOOL,  BACKUPPOOL,  and  SPACEMGPOOL  are  also  provided.  They  all  point  to 
DISKPOOL. 

By  default,  data  that  stored  with  client  nodes  associated  with  BACKUPPOOL  is 
transferred  to  DISKPOOL.  The  data  can  be  stored  in  DISKPOOL  indefinitely  or  can  be 
migrated  to  another  storage  device  in  the  storage  pool  hierarchy. 

To  register  new  client  nodes,  you  provide  a  client  node  name  and  password  for 
each  node  required  (Figure  5-3).  The  new  node  defaults  to  the  STANDARD 
policy  domain.  BACKUPPOOL  is  the  default  storage  pool  for  this  policy  domain. 
Associate  the  client  name  with  the  storage  pool  that  is  set  up  to  maintain  the 
archive  data  on  the  desired  device  type  for  the  period  of  time  that  is  required.  You 
can  associate  the  new  client  node  with  a  different  storage  pool  by  selecting  New 
to  create  a  new  policy  domain. 
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Figure  5-3  Client  node  configuration 

Client  nodes  you  have  registered  can  be  configured  to  back  up  data  to  this  TSM 
server  instance.  The  backup  data  is  managed  according  to  the  way  you  set  up 
the  client’s  associated  storage  pool  hierarchy. 


Note:  The  node  name  and  password  that  you  create  here  are  used  when 
creating  OnDemand  storage  sets  that  uses  TSM  archive. 


Client  options  file 

Each  client  requires  a  client  options  file  which  contains  options  that  identify  the 
node,  the  server,  and  the  communication  method.  The  client  options  file 
(Figure  5-4),  dsm.opt,  can  be  edited  or  created  using  a  standard  text  editor.  Refer 
to  Tivoli  Storage  Manager  for  AIX  Administrator’s  Guide,  GC32-0768,  or  Tivoli 
Storage  Manager  for  Windows  Administrator’s  Guide,  GC32-0782,  for  the  format 
of  the  options  in  the  file.  If  the  client  is  for  a  Windows  system,  there  is  a  Network 
Client  Options  File  Wizard  which  can  be  used  to  create  the  options  file. 
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File  Edit  Format  Help 


"  Note:  This  file  was  generated  by  a  TSM  client  configuration  utility. 

■U 

"  Generated  on  Mon  nov  18  11:26:36  2002 
* 

*  adsm  Administrator:  redbook  &  redbook 


nodename  redbook 

commmethod  TCPIP 

tcpport  1500 

tcpserveraddress  127.0.0.1 


LlJ 


Figure  5-4  dsm.opt  file  sample 


Installation  and  configuration  verification 

At  this  point,  you  should  verify  your  installation  by  performing  backup  of  a  file: 

1 .  Start  the  backup  archive  client  and  log  on  with  the  node  name  and  password 
that  you  created. 

2.  Click  Backup  from  the  client  window. 

3.  Expand  the  directory  tree. 

4.  Select  the  folder  icons  and  select  the  boxes  next  to  the  files  or  directories  that 
you  want  to  back  up  (see  Figure  5-5). 


Chapter  5.  Storage  management  93 


Figure  5-5  Backup  archive  client 

5.  From  the  drop-down  box,  select  the  backup  type. 

6.  Click  Backup.  A  report  window  displays  the  status  of  the  backup. 


Note:  The  first  backup  of  a  file  is  always  a  full  backup,  no  matter  which  backup 
type  you  select. 


You  can  verify  that  the  file  was  backed  up  successfully  by  clicking  the  Restore 
option  in  the  backup  archive  client  (Figure  5-6).  Expand  the  directory  tree  under 
File  level  to  confirm  that  the  files  that  you  backed  up  are  listed.  You  can  also  run 
the  restore  process  to  confirm  that  it  is  working  correctly. 
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ivoli  Storage  Manager  - 


File  Edit  Actions  Utilities  View  Window  Help 

h  *  m  b  %  I 


Figure  5-6  Restore  client 


5.1.2  Configuring  OnDemand  for  TSM  archive  management 

In  order  to  enable  OnDemand  to  use  TSM  as  the  archive  manager  for  the 
system,  OnDemand  options  must  be  set  to  allow  the  system  to  recognize  that 
TSM  has  been  configured  for  archive  storage.  In  an  OnDemand  for  Windows 
system,  the  OnDemand  configurator  is  used  to  set  this  parameter.  In  an 
OnDemand  UNIX  based  system,  the  ars.cfg  configuration  file  is  updated  to 
specify  that  TSM  is  to  be  used. 

OnDemand  for  Windows  TSM  configuration 

If  you  are  configuring  an  OnDemand  for  Windows  system  to  use  TSM  for  archive 
storage,  the  OnDemand  configurator  is  used.  Either  during  the  creation  of  the 
instance  or  after  the  instance  has  been  created,  you  can  select  TSM  as  the 
storage  option  (Figure  5-7).  After  selecting  TSM,  click  TSM  Options,  and  enter 
the  path  to  the  TSM  program  files  and  the  path  to  the  TSM  options  file. 
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ARCHIVE  Properties 


* J 


Instance  |  Server  |  Language  |  Directory  |  Database  Storage 


Configuration 

If  you  select  the  Cache  Only  option,  your  data  will  be  stored  on  hard 
drive  volumes.  If  you  select  TSM,  your  data  will  be  stored  both  on  hard 
drive  volumes  and  archived  media  such  as  optical  volumes. 


C  Cache  Only 
( •  TSM 


TSM  Options. 


Cache  File  | 

Enter  full' 

(ex .  c:  tar  MainD  irectory 


altered  or 


c:\arscai 


Enter  a  directory  name  that  contains  TSM  program  files. 


C:  VProaram  Files\tivoli\tsm\baclient 


Browse.. 


Ai 


Options  File  Path  Name 
Enter  the  full  path  name  for  the  TSM  option  file. 

|  C:  \Program  FilesVT  i voliST  S  M  \baclient\dsm.  opt 


Browse.. 


OK 

Cancel 

Help 

OK 


Cancel 


Apply 


Help 


Figure  5-7  Windows  configurator 


OnDemand  for  UNIX  TSM  configuration 

If  you  are  configuring  an  OnDemand  for  UNIX  system  to  use  TSM  for  archive 
storage,  you  need  to  be  sure  that  the  ars.cfg  file  (Figure  5-8)  has  been  updated 
to  reflect  that  TSM  is  to  be  used  as  the  storage  manager.  The  file  also  needs  to 
include  valid  paths  for  TSM  options  files  and  all  of  the  TSM  components  to  be 
used. 
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#  Storage  Manager  Parameters  (Library/ Object  Server)  # 

mnmmmmmnmmnmummnmmnmum 

n 

#  Storage  Manager  for  OnDemand  to  use 

n 

ARS  STORAGE  MANAGE R=TSM 


mmMmmmmwmmmmwm 

#  TSM  Parameters  (Object  Server  Only)  # 

DSMSERV_DIR=/usr/tivoli/tsm/server/bin 
DSMSERV_CONFIG=/usr/tivoli/tsm/server/bin/ dsmserv. opt 
DSM_D IR=/ usr/ t ivo li/ tsm/ client/ap i/bin 
DSM_CONF IG=/ usr / t ivo 1 1/ tsm/ client/ap i/bin/ dsm .opt 
DSM_LOG=/tmp 

DSMG_D IR=/ usr / t ivo 1 i/ tsm/ client/ap i/bin 

DSMG_CONF IG=/ usr/ t ivo 1 i/ tsm/ client/ap i/bin/ dsm. opt 

DSMG_LOG=/tmp 

DSMI_D IR=/ usr/ t ivo 1 i/ tsm/ client/ap i/bin 
DSMI_CONFIG=/usr/tivoli/ tsm/ client/ap i/bin/ dsm. opt 
DSMI  LOG=/tmp 


Figure  5-8  ARS. CFG  TSM  configuration 


5.1.3  OnDemand  storage  management 

The  storage  management  criteria  that  you  specify  on  the  OnDemand  library 
server  determines  where  and  when  OnDemand  stores  reports  and  how  those 
reports  are  maintained.  Figure  5-9  illustrates  OnDemand  storage  object 
relationships.  When  a  report  is  loaded  into  OnDemand,  it  is  assigned  to  an 
application  group.  The  application  group  is  associated  with  a  storage  set.  The 
storage  set  contains  one  or  more  storage  nodes  that  can  be  used  by  several 
application  groups  which  have  the  same  archive  storage  requirements. 
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For  example,  a  storage  set  can  be  used  to  maintain  data  from  different 
application  groups  that  need  to  retain  documents  for  the  same  length  of  time  and 
need  the  data  to  be  kept  on  the  same  type  of  media.  Different  storage  sets  can 
be  created  to  handle  different  data  retention  requirements.  One  storage  set  can 
be  set  up  to  maintain  data  on  cache  only  DASD  storage.  Another  can  be  set  up 
to  point  to  a  TSM  client  node  that  will  cause  a  copy  of  the  report  to  be  stored  in 
archive  storage. 

If  TSM  is  being  used  as  the  archive  storage  manager,  the  same  storage 
management  criteria  should  be  specified  for  both  OnDemand  and  TSM.  That  is, 

the  Life  of  Data  and  Indexes  in  OnDemand  and  the  retention  period  in  TSM 

should  be  the  same  value. 


98 


Content  Manager  OnDemand  Guide 


Note:  The  date  that  is  used  to  determine  the  Life  of  Data  and  Indexes  in 
OnDemand  is  the  date  field  index  value  taken  from  the  report  being  loaded. 
The  date  used  for  the  retention  period  in  TSM  is  the  date  that  the  report  is  first 
migrated  to  TSM.  If  the  load  type  value  for  the  application  group  is  Load,  a 
command  is  issued  from  OnDemand  to  TSM  to  delete  data  when  the  data  is 
being  expired  from  OnDemand.  If  the  load  type  is  segment  or  document,  a 
delete  command  is  not  issued  from  OnDemand  to  TSM  when  OnDemand 
expires  the  data  and  the  data  remains  in  TSM  until  the  TSM  retention  period 
expires.  This  data  will  not  be  accessible  from  OnDemand  due  to  the  fact  that 
the  indexes  have  been  expired  in  OnDemand. 


5.1.4  Storage  set  definition 

A  storage  set  can  contain  one  or  more  primary  storage  nodes.  A  primary  storage 
node  is  used  to  manage  reports  and  resources  stored  in  an  application  group.  A 
storage  node  is  associated  with  a  specific  OnDemand  object  server.  When  TSM 
is  used  for  archive  storage,  each  storage  node  associated  with  TSM-managed 
storage  must  be  registered  as  a  client  node  in  a  TSM  policy  domain.  The  TSM 
policy  domain  properties  determine  the  type  of  storage  devices  which  are  used  to 
maintain  the  archived  data  and  the  length  of  time  that  the  data  is  maintained. 

OnDemand  systems  can  be  set  up  to  run  as  cache  only  DASD  systems  with  no 
migration  of  the  data  or  indexes,  or  with  an  archive  system  utilizing  TSM  to 
maintain  and  manager  the  archive  of  OnDemand  documents  and  indexes  over  a 
pre-designated  period  of  time.  When  OnDemand  is  installed  and  the  system  is 
initialized,  a  default  cache  only  storage  set  is  created.  Additional  cache  storage 
sets  can  be  defined.  Storage  sets  associated  with  TSM  client  nodes  which  are 
tied  to  specific  management  policies  on  the  TSM  servers  are  used  for  long  term 
archive  storage. 

The  OnDemand  administrator  defines  and  maintains  storage  sets  (Figure  5-10). 
The  load  type  is  the  storage  set  parameter  that  we  examine  here. 
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Figure  5- 1 0  Storage  set  definition 

Load  type 

The  load  type  parameter  determines  where  OnDemand  stores  data.  There  are 

two  possible  values  (Figure  5-10): 

►  Fixed:  OnDemand  stores  data  in  the  primary  storage  node  that  has  the  load 
data  field  selected.  When  load  type  is  set  to  fixed,  you  must  select  the  load 
data  check  box  for  one  primary  storage  node.  OnDemand  loads  data  to  only 
one  primary  storage  node  regardless  of  the  number  of  primary  nodes  that  are 
defined  in  the  storage  set. 

►  Local:  OnDemand  stores  data  in  a  primary  storage  node  on  the  server  on 
which  the  data  loading  program  executes.  When  load  type  is  local,  the  load 
data  check  box  must  be  selected  for  a  primary  storage  node  on  each  of  the 
object  servers  which  is  identified  in  the  storage  set.  A  storage  set  can  contain 
one  or  more  primary  storage  nodes  that  reside  on  one  or  more  object  servers. 
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On  the  primary  node  panel  (Figure  5-11),  there  are  several  parameters  that  we 
need  to  examine. 


Figure  5-11  Primary  node  definition 

Storage  node 

The  OnDemand  storage  node  name  can  be  from  one  to  sixty  characters  in  length 
and  can  include  embedded  blanks.  The  case  can  be  mixed. 


Note:  The  OnDemand  storage  node  name  does  not  tie  the  storage  set  to  the 
TSM  client  node.  This  name  is  only  a  label  in  the  OnDemand  system.  The 
storage  node  name  can  be  the  same  as  the  associated  client  node  name,  but 
it  is  not  required  that  they  be  the  same. 
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Logon 

If  TSM  is  being  used  to  maintain  archive  data,  the  logon  parameter  is  the  name 
of  the  TSM  client  node.  This  parameter  is  ignored  if  you  are  defining  a  cache  only 
storage  node. 


Note:  The  logon  field  must  be  a  valid  TSM  client  node  name.  This  is  the  client 
node  that  has  been  defined  on  the  TSM  system  through  the  wizard  or 
command  line.  The  password  which  follows  the  logon  must  be  the  same  as 
the  password  created  for  the  client  node.  OnDemand  uses  a  TSM  API  to 
connect  and  logon  to  the  TSM  server  when  data  is  being  migrated  to  the  TSM 
client  node. 


Load  data 

The  load  data  parameter  determines  the  primary  storage  node  into  which 
OnDemand  loads  data.  When  the  load  type  is  fixed,  one  primary  storage  node 
must  have  load  data  selected.  When  load  type  is  local,  load  data  must  be 
selected  for  one  primary  node  for  each  object  server  that  is  associated  with  the 
storage  set. 

Cache  only 

The  cache  only  parameter  determines  whether  OnDemand  uses  the  archive 
manager  for  long  term  storage  of  data. 

After  installing  and  configuring  TSM,  creating  an  OnDemand  storage  set,  and 
assigning  it  to  a  TSM  client  node,  we  are  ready  to  consider  how  an  application 
group  uses  the  cache  storage  manager  and  the  archive  storage  manager  to 
store,  maintain,  and  expire  OnDemand  report  data. 
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5.1.5  Application  group  storage  management 

The  application  group  storage  management  settings  (Figure  5-12)  determine 
how  long  report  data  and  indexes  are  kept  in  cache  storage  before  being  expired. 
There  are  also  choices  to  be  made  concerning  how  soon  data  is  migrated  to  the 
archive  storage  after  the  report  load  is  completed. 


Figure  5- 12  Application  group  storage  management 

Cache  data 

The  cache  data  setting  determines  if  the  report  data  is  stored  in  DASD  cache 
and,  if  so,  how  long  it  is  kept  in  cache  before  it  is  expired.  You  can  also  choose  to 
have  cache  searched  or  not  searched  when  retrieving  documents  for  viewing.  If 
you  choose  not  to  store  reports  in  cache,  a  storage  set  that  supports  archive 
storage  must  be  selected. 
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Note:  Data  that  is  retrieved  often  should  generally  remain  in  cache  until  it  is  no 
longer  needed  by  90%  of  OnDemand  users. 


Life  of  data  and  indexes 

The  life  of  data  and  indexes  settings  determine  the  length  of  time  that  report 
data,  indexes  and  resources  are  maintained  in  the  OnDemand  system  before 
they  are  deleted  from  the  application  group.  The  report  data,  indexes,  and 
resources  can  be  maintained  indefinitely  if  set  to  never  expire,  or  may  be  kept  for 
up  to  273  years.  After  the  maintenance  threshold  has  been  reached,  the 
arsmaint  command  can  be  used  to  expire  the  data  from  the  system. 

Expiration  type 

The  expiration  type  determines  how  report  data,  indexes  and  resources  are 
expired.  There  are  three  expiration  types: 

►  Load:  If  the  expiration  type  is  load,  an  input  file  at  a  time  can  be  deleted  from 
the  application  group.  The  latest  date  in  the  input  data  and  the  life  of  data  and 
indexes  determines  when  OnDemand  deletes  the  data.  Data  that  has  been 
stored  in  archive  storage  is  deleted  by  the  storage  manager  based  on  the 
archive  expiration  date.  Load  is  the  recommended  expiration  type. 

►  Segment:  If  the  expiration  type  is  segment,  a  segment  of  data  at  a  time  is 
deleted  from  the  application  group.  The  segment  must  be  closed  and  the 
expiration  date  of  every  record  in  the  segment  must  have  been  reached.  If 
small  amounts  of  data  are  loaded  into  the  application  group,  and  the 
maximum  rows  value  is  high,  the  segment  may  be  open  for  a  long  period  of 
time  and  the  data  is  not  be  expired  for  the  period. 

►  Document:  If  the  expiration  type  is  document,  a  document  at  a  time  is 
deleted  from  the  application  group.  Storing  with  an  expiration  type  of 
document  causes  the  expiration  process  to  search  through  every  document  in 
the  segment  to  determine  if  the  expiration  date  has  been  reached  resulting  in 
long  processing  times. 

When  the  arsmaint  expiration  process  is  run,  data  is  only  be  deleted  from  the 
application  group  if  the  upper  threshold  for  the  size  of  cache  storage  has  been 
reached.  By  default,  the  cache  threshold  is  80  percent.  A  lower  threshold  can  be 
forced  by  the  expiration  command  parameters.  However,  unless  there  is  some 
reason  that  cache  needs  to  be  cleared,  leaving  data  in  cache  improves  retrieval 
performance. 
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5.1.6  Advanced  application  group  storage  management 

The  advance  storage  management  settings  (Figure  5-13)  allow  you  to  adjust  the 
size  of  the  load  object  and  to  determine  when  report  data,  indexes,  and 
resources  are  migrated  to  archive  storage. 


Figure  5-13  Advanced  application  group  storage  management 

Object  size 

The  object  size  parameter  determines  the  size  of  a  storage  object  in  kilobytes. 
OnDemand,  by  default,  segments  and  compresses  stored  data  into  10  MB 
storage  objects.  The  default  10  MB  is  the  recommended  object  size  value. 
Caution  should  be  exercised  when  changing  the  value.  Too  small  or  too  large  of  a 
value  can  have  an  adverse  affect  on  load  performance. 


Note:  The  object  size,  defined  here,  must  be  equal  to  or  larger  than  the  size  of 
the  compressed  storage  objects  defined  in  any  application  assigned  to  the 
application  group. 
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Migrate  data  from  cache 

This  determines  when  documents  and  resources  are  migrated  to  archive 
storage.  A  storage  set  associated  with  a  TSM  client  node  must  be  selected  to 
enable  migration  to  archive  storage.  Possible  values  are: 

►  No:  Data  is  never  migrated  from  cache.  This  option  is  greyed  out  when  a 
storage  set  associated  with  a  TSM  client  node  is  selected  for  the  application 
group. 

►  When  data  is  loaded:  Data  is  migrated  to  archive  storage  when  the  data  is 
loaded  into  the  application  group. 

►  Next  cache  migration:  Data  is  migrated  to  archive  storage  the  next  time  that 
ARSMAINT  is  run  with  the  -m  option.  The  -m  option  indicates  that  data  and 
resources  are  to  be  copied  from  cache  to  archive  storage. 

►  After _ days  in  cache:  Specifies  the  number  of  days  that  data  is  to  remain 

in  cache  only  storage.  After  reaching  the  prescribed  number  of  days  in  cache 
storage,  the  data  is  copied  to  archive  storage  the  next  time  that  ARSMAINT  is 
run  with  the  -m  option  for  data  migration. 

5.1.7  ARSMAINT 

Since  the  OnDemand  command  arsmaint  has  already  been  referenced  many 
times  in  the  earlier  sections,  we  now  take  a  quick  look  at  arsmaint.  The  arsmaint 
program  maintains  application  group  data  that  is  stored  in  the  OnDemand 
database  and  in  cache  storage.  It  maintains  the  system  using  the  storage 
management  values  that  are  specified  for  application  groups.  It  is  typically  run  in 
a  regular  schedule  to  migrate  documents  from  cache  storage  to  archive  storage, 
migrate  index  data  to  archive  storage,  and  delete  documents  from  cache  storage 
and  index  data  from  the  OnDemand  database. 

arsmaint  uses  the  application  group  expiration  type  to  determine  howto  delete 
index  data  from  an  application  group,  arsmaint  can  expire  a  table  of  application 
group  data  at  a  time  (segment  expiration  type),  an  input  file  of  data  at  a  time 
(load  expiration  type),  or  individual  documents  (document  expiration  type). 


Note:  When  expiring  cache  data,  by  default,  the  data  is  not  expired  until  the 
cache  storage  file  system  has  exceeded  80  percent  of  capacity.  Keeping  data 
in  cache  as  long  as  possible  improves  retrieval  and  viewing  performance.  You 
can  force  the  expiration  of  cache  data  before  cache  is  80  percent  full  by  using 
the  minimum  and  maximum  parameters  to  override  the  percentage  full  default. 


Refer  to  IBM  Content  Manager  OnDemand  for  Multiplatforms  -  Administrator’s 
Guide,  SC27-0840  for  detailed  explanation  of  the  arsmaint  command  and  its 
associated  parameters,  along  with  all  other  OnDemand  commands. 
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5.2  Object  Access  Method  for  z/OS 

Although  there  is  a  separate  redbook  on  the  Object  Access  Method  (OAM)  and 
some  very  good  documentation  on  this  product,  here  we  provide  an  introduction 
to  OAM  and  show  its  relationship  with  OnDemand  in  a  z/OS  environment.  For 
more  information  about  setting  up  OAM,  refer  to  DFSMS  Object  Access  Method 
Planning,  Installation,  and  Storage  Administration  Guide  for  Object  Support, 
SC35-0426. 

OAM  is  the  DFSMSdfp  component  that  manages  a  class  of  data,  called  objects, 
in  a  z/OS  environment.  Objects  are  bit  strings  which  are  handled  as  one  big  byte 
string  rather  than  processing  them  as  records,  as  is  done  with  data  sets.  The 
content  of  this  byte  string  is  not  known  to  OAM.  There  are  no  restrictions  on  the 
data  type  of  this  object  —  it  can  be  an  image,  compressed  data,  or  coded  data. 

Flow  to  handle  this  data  is  left  up  to  the  application.  OAM  is  designed  to  handle 
an  unlimited  number  of  objects,  which  can  be  stored  on  magnetic  disk,  magnetic 
tape,  or  optical  storage.  Objects  are  different  from  data  sets,  which  are  handled 
by  existing  access  methods.  The  following  characteristics  distinguish  them  from 
traditional  data  sets: 

►  Lack  of  record  orientation:  There  is  no  concept  of  individual  records  within 
an  object. 

►  Broad  range  of  size:  An  object  may  contain  less  than  one  kilobyte  or  up  to 
50  megabytes  of  data. 

►  Volume:  Objects  are  usually  much  smaller  than  data  sets;  however,  they  can 
use  much  more  external  storage,  depending  on  the  kind  of  application 
creating  them,  such  as  image  applications. 

►  Access  time  requirements:  Reference  patterns  for  objects  change  over 
time,  allowing  less  critical  objects  to  be  placed  on  lower  cost,  slower  devices, 
or  media. 


5.2.1  OAM  components  and  SMS  terminologies 

In  this  section,  we  describe  the  three  components  of  OAM  and  the  OAM 
terminologies. 
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OAM  components 

The  functions  of  OAM  are  performed  by  three  components: 

►  Object  Storage  and  Retrieval  (OSR)  component:  Provides  an  application 
programming  interface  (API)  for  OAM.  All  OAM  API  functions  are  requested 
via  the  OSREQ  assembler  macro.  Applications  use  this  interface  to  store, 
retrieve,  query,  and  delete  objects,  as  well  as  to  change  information  about 
objects.  OSR  stores  the  objects  in  the  storage  hierarchy  and  maintains  the 
information  about  these  objects  in  DB2  databases.  OSR  functions  invoked 
through  the  application  programming  interface  require  the  OAM  Thread 
Isolation  Support  (OTIS)  application  for  administrative  processing. 

►  Library  Control  System  (LCS)  component:  Writes  and  reads  objects  on 
tape  and  optical  disk  storage.  It  also  manipulates  the  volumes  on  which  the 
objects  reside.  The  LCS  component  controls  the  usage  of  optical  hardware 
resources  that  are  attached  to  the  system. 

►  OAM  Storage  Management  Component  (OSMC):  Determines  where 
objects  should  be  stored  in  the  OAM  storage  hierarchy,  manages  object 
movement  within  the  object  storage  hierarchy,  manages  expiration  attributes 
that  are  based  on  the  installation  storage  management  policy  that  is  defined 
through  SMS,  and  creates  the  requested  backup  copies  of  the  objects.  OSMC 
also  provides  object  and  volume  recovery  functions. 

SMS  terminologies 

To  provide  a  better  understanding  of  OAM,  we  explain  some  SMS  terms: 

SMS  storage  class:  A  storage  class  is  a  collection  of  performance  goals  and 
availability  and  accessibility  requirements  that  are  defined  to  SMS.  It  is  used  to 
select  a  device  to  meet  those  goals  and  requirements. 

Usually,  three  storage  classes  are  set  up  for  OAM  where  the  names  of  the 
storage  classes  are  set  up  by  the  storage  administrator  based  on  the  naming 
convention  in  the  Enterprise.  These  storage  classes  are: 

►  OAMDASD:  Objects  are  stored  in  a  DB2  table  on  fast  magnetic  disk. 

►  OAMTAPE:  Objects  are  stored  on  magnetic  tape  including  tape  robots. 

►  OAMOPTIC:  Objects  are  stored  on  a  3995  optical  device. 


Note:  The  cache  storage  on  an  HFS  file  system  is  not  part  of  these  SMS 
constructs. 
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SMS  storage  group:  An  SMS  storage  group  is  a  collection  of  storage  volumes 
and  attributes  that  are  defined  by  the  installation.  Storage  groups,  along  with 
storage  classes,  help  reduce  the  requirement  for  users  to  understand  the 
physical  characteristics  of  the  storage  devices  which  contain  their  data. 

In  an  OAM  environment,  Object  Storage  Groups  allow  the  storage  administrator 
to  define  an  object  storage  hierarchy.  The  object  storage  hierarchy  classifies 
storage  areas  according  to  location  and,  therefore,  according  to  retrieval 
response  time.  Each  object  storage  hierarchy  must  contain  an  object  directory, 
containing  control  information  about  each  object.  Additionally,  the  hierarchy  can 
have: 

►  DB2  object  storage  tables  on  DASD 

►  Optical  volumes  that  are  associated  with  optical  libraries  (real  or  pseudo),  and 
stand-alone  or  operator-accessible  optical  disk  drives 

►  Tape  volumes  that  are  associated  with  tape  libraries  or  stand-alone  tape 
drives 

SMS  Management  Class:  Management  classes  define  the  space  and 
availability  requirements  for  data  sets.  Class  attributes  control  backup,  migration, 
retention  of  data,  and  release  of  unused  space.  OSMC  uses  information  from  the 
management  classes  to  determine  which  automatic  management  processes 
should  be  performed  upon  corresponding  OAM  objects. 

Automated  Class  Selection  (ACS)  routine:  ACS  routines  are  used  to  assign 
class  and  storage  group  definitions  to  data  sets  and  objects.  ACS  routines  are 
written  in  the  ACS  language,  which  is  a  high-level  programming  language  similar 
to  that  used  for  the  construction  of  TSO  CLISTs.  The  ACS  translator  is  used  to 
convert  the  routines  to  object  form  so  they  can  be  stored  in  the  SMS 
configuration. 

OAM  Collection:  A  collection  is  a  group  of  objects  typically  having  similar 
performance,  availability,  backup,  retention,  and  class  transition  characteristics. 
A  collection  is  used  to  catalog  a  large  number  of  objects,  which,  if  cataloged 
separately,  could  require  an  extremely  large  catalog.  Every  object  must  be 
assigned  to  a  collection.  Object  names  within  a  collection  must  be  unique; 
however,  the  same  object  name  can  be  used  in  multiple  collections.  Each 
collection  belongs  to  one  and  only  one  Object  storage  group.  Each  storage  group 
can  contain  from  one  to  many  collections. 


Important:  A  collection  is  the  only  interface  used  by  the  administrator  to 
determine  how  to  store  objects  in  OAM.  It  is  used  when  creating  a  storage  set. 
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5.2.2  Defining  a  storage  set 

When  the  OnDemand  administrator  defines  a  new  storage  set,  a  screen  as 
shown  in  Figure  5-14  is  displayed. 


Figure  5- 14  Add  a  storage  set 

Values  must  be  defined  for  the  following  fields  to  add  a  new  storage  set: 

►  Name:  The  name  of  the  storage  set. 

►  Description:  The  storage  set  description,  up  to  120  characters. 

►  Load  type:  This  determines  where  OnDemand  stores  data. 

There  are  two  choices: 

-  Fixed:  OnDemand  stores  data  in  the  primary  storage  node  that  has  the 
load  data  field  selected.  When  you  set  load  type  to  Fixed,  you  must  select 
the  load  data  check  box  for  one  primary  storage  node.  A  storage  set  can 
contain  one  or  more  primary  storage  nodes.  There  can  be  several  different 
collection  names. 

-  Local:  OnDemand  stores  data  in  a  primary  node  on  the  server  on  which 
the  data  loading  program  executes.  This  applies  to  z/OS. 
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Click  Add  to  add  a  primary  storage  node  to  this  storage  set,  and  you  get  a 
screen  as  shown  in  Figure  5-15. 


Figure  5-15  Add  a  primary  storage  node  to  the  storage  set 

The  object  server  is  always  OnDemand  if  the  OD/390  object  server  check  box  is 
selected.  The  load  data  check  box  indicates  that  the  data  is  loaded  to  this 
collection.  You  need  to  select  OAM  on  the  check  box.  The  logon  and  password 
fields  are  not  used  in  a  z/OS  environment.  These  fields  are  for  TSM  only. 

There  is  a  one-to-one  relationship  between  a  collection  and  a  storage  set.  You 
can  add  more  primary  storage  nodes  to  one  storage  set,  but  only  one  can  be 
active  at  a  time. 

Figure  5-16  shows  the  relationship  between  the  creation  of  storage  sets  and 
OAM. 
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Object  naming  conventions 

The  object  name  identifies  the  object  within  a  collection.  The  object  name  is 
unique  within  a  collection  and  is  provided  by  the  OnDemand  application.  There 
are  currently  no  installation  exits  which  allow  for  any  customizing  of  these 
names.  The  object  name  is  composed  of  the  application  group  name,  the  load 
identifier  within  the  application  group  portion  of  the  load  ID.  The  load  identifier 
within  the  application  group  is  composed  by  a  numeric  sequence  number 
followed  by  a  character  string  such  as  FAAA.  This  string  is  then  converted  into 
two  qualifiers  of  the  object  name: 

►  L  indicates  that  the  object  contains  document  data 

►  R  indicates  that  the  object  contains  resource  data 

The  application  group  name  is  added,  and  an  object  name  looks  like  this: 

A  AAAAAAA.L1.FAAA 
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The  maximum  size  of  an  object  is  specified  via  the  OnDemand  Administration 
GUI  when  defining  an  application  group.  The  default  value  is  10  MB.  Currently, 
the  maximum  size  for  an  OAM  object  is  50  MB.  The  OnDemand  administrator 
must  be  careful  not  to  specify  a  value  exceeding  this  limit. 


Attention:  In  the  current  implementation,  OnDemand  is  not  aware  that  an 
object  has  been  deleted  by  OAM  based  on  management  class  criteria  set  by 
the  Storage  Management  component.  An  end  user  can  search  for  data  which 
is  no  longer  available.  There  is  no  synchronization  between  OAM  object 
expiration  and  index  expiration.  Be  sure  to  define  the  index  expiration  correctly 
when  defining  the  application  group. 


Figure  5-17  shows  the  panel  where  you  can  set  up  the  expiration  for  Storage 
Management  when  defining  or  updating  an  application  group. 


Figure  5-17  Defining  index  expiration  in  OnDemand 


Tip:  OnDemand  and  OAM  can  run  in  different  DB2  subsystems  (different  DB2 
SSID). 
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5.2.3  Storing  data  to  Virtual  Storage  Access  Method  data  sets 

Another  way  of  storing  data  on  the  z/OS  system  is  via  the  Virtual  Storage  Access 
Method  (VSAM).  OnDemand  can  create  objects  which  are  stored  in  a  VSAM 
data  sets.  All  Storage  Management  issues  for  VSAM  data  sets  such  as 
allocation,  backup,  migration  apply  for  these  object  data  sets. 

To  create  a  storage  set  which  stores  to  VSAM,  the  OnDemand  administrator  has 
to  provide  the  first  level  qualifier  for  the  defined  cluster  statement.  In  the  example 
as  shown  in  Figure  5-18,  TEAM5  is  the  high  (first)  level  qualifier. 


Figure  5-18  Defining  a  storage  set  for  VSAM 

Based  on  this  parameters,  OnDemand  creates  a  VSAM  data  sets  during  the 
arsload.  A  catalog  entry  as  shown  in  Example  5-1  is  created. 

Example  5-1  VSAM  data  set  name 
TEAM5. FAA. LI. FAAA 
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This  is  done  automatically  by  the  OnDemand  system.  The  only  part  you  can 
create  for  yourself  is  the  first  level  qualifier.  The  space  allocation  during  the 
Define  Cluster  is  done  by  the  OnDemand  code  as  well.  The  default  object  size 
set  when  defining  the  application  group  influences  the  number  of  bytes  for  the 
primary  and  the  secondary  allocation.  The  number  of  bytes  is  divided  by  16  for 
the  primary  allocation.  So  every  time  an  arsload  is  done  with  this  storage  set, 
this  amount  of  data  is  allocated  even  if  the  objects  are  much  smaller. 

Every  load  creates  two  VSAM  data  sets,  one  for  the  data,  and  one  for  the  index. 
Every  Define  Cluster  of  a  VSAM  data  set  is  a  catalog  entry.  If  you  have  several 
million  loads  with  this  storage  set,  your  catalog  can  grow  very  large. 

You  can  browse  the  VSAM  data  set;  but  if  the  compression  is  on,  you  cannot  see 
much.  For  test  purpose  compression  can  be  switched  off  and  the  content  of  the 
VSAM  data  set  is  viewable.  Compression  can  be  switched  off  on  the  load 
information  on  the  application  panel. 

If  you  store  AFP  data  to  VSAM,  the  resources  are  stored  in  a  different  VSAM 
data  set. 


5.3  Archive  Storage  Manager  for  iSeries 

OnDemand  for  iSeries  Disk  Storage  Manager  (DSM)  maintains  a  copy  of 
documents  on  disk.  DSM  migrates  documents  from  cache  to  the  Archive  Storage 
Manager  (ASM).  ASM  then  migrates  documents  to  archive  media. 

ASM  maintains  one  or  more  copies  of  documents  on  archive  media,  such  as 
optical  or  tape.  The  OnDemand  administrator  decides  which  type  of  media  that 
the  OnDemand  system  requires,  configures  the  storage  devices  on  the  systems, 
and  defines  the  storage  devices  to  ASM.  To  store  application  group  data  on 
archive  media,  the  application  group  must  be  assigned  to  a  storage  set  that  is 
managed  by  ASM. 

When  creating  an  application  group,  the  OnDemand  administrator  specifies  how 
long  documents  should  be  maintained  on  the  system  and  whether  the  index  data 
should  be  migrated  from  the  database  to  archive  media.  OnDemand  system 
management  programs  use  this  information  to  migrate  documents  from  disk  to 
archive  media,  delete  documents  from  disk,  migrate  index  data  from  the 
database  to  archive  media,  and  delete  index  data  from  the  database.  OnDemand 
can  then  reclaim  the  space  which  had  been  used  by  the  migrated  and  expired 
data. 
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ASM  deletes  data  from  the  archive  media  when  it  reaches  its  storage  expiration 
date.  The  OnDemand  administrator  defines  management  information  to  the 
archive  storage  manager  for  the  OnDemand  data  that  is  to  be  managed.  This 
management  information  includes  storage  volumes  that  can  contain  OnDemand 
data,  the  number  of  copies  of  a  report  to  maintain,  and  how  long  to  keep  data  in 
the  archive  management  system. 

DSM  and  ASM  manage  and  delete  data  independently  of  each  other.  Each  uses 
its  own  criteria  to  determine  when  to  remove  documents.  Each  uses  its  own 
utilities  and  schedules  to  remove  documents.  For  final  removal  of  documents 
from  the  system,  the  same  criteria  should  be  given  for  DSM  and  ASM. 


5.3.1  Migration  policy 

Migration  policies  and  storage  sets  must  be  defined  before  you  can  define 
reports  to  OnDemand  or  load  data  into  the  system.  Migration  policies  contain 
migration  and  storage  media  characteristics  for  data  archived  using  OnDemand. 
The  information  is  used  by  ASM  to  determine  if  and  when  archived  data  should 
be  moved  through  a  hierarchy  of  storage  media,  such  as  disk,  optical,  or  tape. 
Each  step  in  the  movement  of  data  through  this  storage  hierarchy  is  referred  to 
as  a  migration  policy  storage  level.  Each  migration  policy  must  contain  at  least 
one  storage  level,  additional  levels  may  be  defined  to  meet  your  storage  and 
retrieval  requirements. 

A  migration  policy  is  only  required  if  you  migrate  data  from  Cache  to  other  media, 
such  as  optical,  tape,  or  a  disk  pool.  Even  though  you  may  not  plan  to  use  any 
media  other  than  Cache,  you  may  change  your  mind  later.  Therefore,  it  is  a  good 
idea  to  always  create  a  migration  policy,  even  if  the  only  level  you  specify  is  the 
disk  pool  storage  ASP01  (the  system  ASP).  When  you  create  a  migration  policy, 
a  storage  set  of  the  same  name  is  automatically  created  by  OnDemand.  If  you 
know  you  want  to  keep  your  archives  for  seven  years,  for  example,  you  could 
specify  1  day  in  Cache  and  2555  days  for  the  Life  of  Data  and  Indexes  in  the 
application  group.  Specify  90  days  for  the  ASP01  level  in  the  migration  policy  and 
do  not  specify  an  expiration  level. 

If  you  take  the  default  in  the  application  group  to  migrate  data  from  Cache  when 
data  is  loaded,  then  a  copy  of  the  data  is  archived  to  the  IFS  Cache  directory  and 
to  the  IFS  ASMASP01  directory.  When  you  run  DSM,  the  data  is  deleted  from 
Cache.  When  you  run  ASM,  the  data  remains  in  ASP01  until  the  number  of  days  in 
the  Life  of  Data  and  Indexes  is  reached,  or  an  expiration  level  in  the  migration 
policy  is  encountered  —  whichever  comes  first.  In  the  QPRLCASM1  status  report 
created  by  ASM,  you  get  messages  that  the  number  of  days  in  the  ASP01  level 
has  been  exceeded,  but  you  can  ignore  these  messages.  In  future,  if  you  add  an 
optical  jukebox,  you  can  add  an  optical  level  to  the  migration  policy.  All  data  that 
has  been  in  ASP01  for  more  than  90  days  (in  this  example)  is  migrated  to  optical. 
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While  most  administrative  functions  for  an  OnDemand  for  iSeries  Common 
Server  can  be  carried  out  with  the  OnDemand  administrator  client,  creating  the 
objects  necessary  for  OnDemand  archive  storage  management  on  the  iSeries 
must  be  done  through  Client  Access  Operations  Navigator  with  the  OnDemand 
plug-in  (Figure  5-19). 


Figure  5-19  iSeries  operation  navigator 

In  order  to  create  a  migration  policy,  there  must  be  storage  devices  defined  for 
the  types  of  archive  media  required  by  the  OnDemand  system.  For  the  purposes 
of  our  scenario,  we  have  created  a  disk  pool  storage  group  and  an  optical 
storage  group. 

Disk  pool  storage  group 

A  disk  pool  storage  group  is  used  to  identify  an  OS/400  auxiliary  storage  pool 
that  ASM  uses  as  disk  storage  media  when  migrating  archived  data.  Using 
Operations  Navigator  to  add  a  disk  pool  storage  group  (Figure  5-20). 
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Figure  5-20  iSeries  Disk  Pool  definition 

Provide  the  following  information  for  Disk  Pool  definition  (Figure  5-20): 

►  A  pool  number  which  corresponds  to  an  existing  auxiliary  storage  pool 

►  A  description  of  the  storage  group 

►  The  type  of  data,  primary  or  backup 

►  The  OnDemand  instance  with  which  the  storage  group  is  associated 

Optical  storage  group 

Optical  storage  groups  are  used  by  OnDemand  to  group  sets  of  optical  volumes 
for  the  storage  of  related  data.  By  using  a  specific  storage  group  in  the  migration 
policy,  the  administrator  can  control  which  sets  of  reports  are  stored  on  specific 
optical  volumes.  Operations  Navigator  is  used  to  define  the  optical  storage  group 
(Figure  5-21). 
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Figure  5-21  iSeries  optical  storage  group 

When  defining  the  optical  storage  group  (Figure  5-21),  you  provide: 

►  Storage  group  name. 

►  Description  of  the  storage  group. 

►  Volume  full  reset  when  optical  volumes  are  rewritable  and  you  wish  to  reuse 
the  storage  space  (only  available  with  LAN-attached  optical  jukeboxes). 

►  Free  space  threshold  percent  is  the  percent  at  which  OnDemand  starts 
storing  to  rewritable  volumes  again  if  the  volume  full  reset  parameter  is 
checked. 

►  Storage  group  type,  primary  or  backup. 

►  The  OnDemand  instance  with  which  the  storage  group  is  associated. 

After  defining  the  optical  storage  group,  Operations  Navigator  is  used  to  define 

optical  volumes  to  the  OnDemand  system  (Figure  5-22). 
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Figure  5-22  iSeries  optical  volume 

When  defining  optical  volumes  (Figure  5-22),  you  provide  this  information: 

►  Volume  name:  Your  volume  name 

►  Volume  type:  Primary  or  backup 

►  Instance:  OnDemand  instance  with  which  the  optical  volume  is  associated 

►  Capacity  in  megabytes:  Capacity  of  one  side  of  the  optical  media,  after  it 
has  been  initialized 

►  Optical  media  family:  Rewritable  (REWT)  or  write-once-read-many  (WORM) 

►  Optical  storage  group:  Your  optical  storage  group 

►  Optical  library:  Library  name,  which  can  be  provided  for  documentation 

►  Volume  is  full:  This  indicator  is  set  when  the  optical  volume  reaches  its 
capacity. 

►  Opposite  side  volume  name:  This  is  for  the  other  side  of  the  optical  platter. 
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Once  the  storage  groups  have  been  established,  the  migration  policy  needed  to 
use  them  can  be  defined  using  Operations  Navigator  (Figure  5-23). 


Figure  5-23  iSeries  migration  policy 

The  migration  policy  definition  (Figure  5-23)  includes: 

►  Policy  name  and  description:  Field  for  the  policy  name  and  its  description. 

Tip:  It  is  a  good  practice  to  put  information  such  as  “length  of  time  and 
where  located”  in  the  description  rather  than  the  policy  name  field.  This  is 
because  you  can  change,  add,  and  delete  levels,  but  you  cannot  change 
the  name.  You  do  not  want  to  be  “stuck”  with  a  name  that  is  no  longer 
accurate. 
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►  Enable  aggregation:  If  selected,  ASM  combines  individual  archived  objects 
into  larger  objects  to  provide  efficient  process.  Archive  objects  are  appended 
to  the  same  file  until  the  aggregate  is  closed. 

►  Maximum  size:  Determines  the  maximum  size  of  the  aggregate  file.  ASM 
closes  the  existing  aggregate  and  opens  a  new  aggregate  when  the 
maximum  value  is  reached. 

►  Close  aggregate  only  when  maximum  size  reached:  If  selected,  the 
aggregate  stays  open  until  the  maximum  is  reached. 

►  Close  aggregate  after  specified  time  period:  Specify  the  number  of  days 
before  an  aggregate  closes.  ASM  closes  the  aggregate  after  the  specified 
number  of  days  or  when  the  specified  maximum  size  is  reached,  whichever 
occurs  first. 


Important:  The  aggregation  process  occurs  prior  to  the  migration  of  the  object 
from  disk  to  the  first  ASM  storage  level.  Only  aggregate  files  that  have  closed 
are  eligible  for  migration  by  ASM.  If  the  specified  maximum  file  size  is  large 
and  the  size  of  migrations  is  small,  the  aggregate  file  could  remain  open  for 
long  periods  and  the  OnDemand  objects  may  remain  on  disk  longer  than  the 
period  specified  by  the  application  group.  Choosing  to  close  the  aggregate 
after  a  specified  period  of  time  addresses  this  problem. 


►  Tape  backup  requested  and  media  type:  Specifies  whether  a  one-time  tape 
backup  should  be  made  of  the  data  before  it  is  archived,  and  specifies  the 
type  of  tape  to  use  for  the  backup. 

►  Instance:  The  OnDemand  instance  with  which  the  migration  policy  is 
associated. 

Storage  level  in  this  policy:  Determines  the  path  the  archived  data  follows 
through  the  different  archive  storage  media.  The  order  of  the  levels  determines 
the  migration  sequence.  Storage  levels  are  created  by  placing  the  cursor  on  an 
existing  storage  level  (if  one  exists)  and  clicking  the  Add  Before  or  Add  After 
button.  The  new  policy  level  panel  (Figure  5-24)  is  opened. 
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Figure  5-24  iSeries  new  policy  level 

Provide  the  following  information  for  the  new  storage  level  (Figure  5-24): 

►  Level  identifier:  Distinguishes  the  different  storage  levels  within  the  migration 
policy.  The  value  must  be  unique  within  the  storage  levels  of  the  migration 
policy.  ASM  uses  the  level  identifier  to  determine  current  level  of  the  migration 
hierarchy  and  to  determine  the  next  level  to  which  the  data  should  be  moved. 

►  Disabled:  Causes  ASM  to  skip  this  level  in  the  storage  hierarchy.  The 
disabled  parameter  can  be  used  in  a  situation  where  an  optical  unit  is  added 
to  the  system  later,  but  the  administrator  wishes  to  go  ahead  and  add  an 
optical  policy  level  and  disable  it.  Disabled  can  also  be  used  when  migration 
to  a  policy  level  is  to  be  discontinued,  such  as  a  tape  unit.  A  policy  level  may 
not  be  removed  if  data  is  archived  to  it;  but  it  may  be  disabled  so  that  no  more 
data  gets  migrated  to  that  level. 

►  Description  of  the  policy  level:  Field  for  a  description  of  the  policy  level. 
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►  Media  type:  Optical,  tape,  disk,  or  expire.  If  expire  is  selected  as  the  last 
policy  level,  when  data  reaches  this  level  in  the  migration  sequence,  it  is 
removed  from  the  archive  system  even  if  the  retention  period  specified  in  the 
application  group  has  not  been  exceeded.  It  is  not  necessary  to  specify  an 
expire  level.  Instead,  you  can  just  let  the  data  expire  when  it  has  exceeded  the 
number  of  days  specified  in  the  Life  of  Data  and  Indexes  in  the  application 
group. 

►  Duration  at  this  level:  Either  no  maximum,  or  a  specified  number  of  days 
before  ASM  moves  the  data  to  the  next  level  in  the  migration  sequence. 

►  Primary  storage  group:  Select  the  storage  group  that  you  wish  to  use  to 
store  the  data  at  this  level. 

►  Create  backup  copy  and  backup  storage  group:  Select  this  option  if  you 
want  ASM  to  create  a  backup  copy  of  the  data  when  it  moves  to  this  policy 
level.  The  backup  storage  group  must  have  been  created  with  a  type  of 
backup. 

►  Stage  to  disk  if  retrieved  from  tape  and  duration  on  disk:  Choose  this 
option  to  cache  data  returned  from  tape  to  disk  for  the  number  of  days 
specified. 

In  our  scenario,  we  created  a  policy  level  which  stores  data  for  90  days  on  disk 
using  the  disk  pool  storage  group  assigned  to  auxiliary  storage  pool  1 .  We  also 
created  an  policy  level  which  stores  data  on  optical  for  3  years  and  uses  the 
Redbook  optical  storage  group.  Finally,  we  included  an  expire  policy  level  which 
removes  the  data  from  archive  storage  at  the  end  of  the  3-year  period  on  optical 
storage.  Figure  5-25  shows  the  final  migration  policy  structure. 


Note:  When  the  migration  policy  is  created,  a  corresponding  storage  set  is 
created  for  the  Content  Manager  instance  with  which  the  migration  policy  is 
associated.  The  storage  set  will  appear  in  a  listing  of  storage  sets  using  the 
OnDemand  Administrator  Client  but  can  only  be  viewed.  No  updates  can  be 
made  to  existing  storage  sets  and  no  new  storage  sets  can  be  added  using 
the  Administrator  Client.  Storage  sets  in  the  OnDemand  for  iSeries  system 
can  only  be  created  and  modified  through  the  use  of  Operations  Navigator 
and  migration  policies. 
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New  Migration  Policy  -  Pwd4820.svo.dfw.ibm.com 
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Figure  5-25  iSeries  migration  policy  hierarchy 


OK 

Cancel 

Help 

5.3.2  Application  group  storage  management 

The  application  group  storage  management  settings  (Figure  5-26)  determine 
how  long  report  data  and  indexes  are  kept  in  cache  storage  before  being  expired. 
All  documents  in  the  application  group  are  loaded  on  the  media  that  is  part  of  the 
storage  set  to  which  the  application  group  is  assigned.  All  documents  in  the 
application  group  migrate  according  to  the  rules  that  are  defined  for  the 
application  group’s  migration  policy.  When  defining  the  application  group, 
choices  are  made  concerning  how  soon  data  is  migrated  to  archive  storage  after 
the  report  load  is  completed. 
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Figure  5-26  iSeries  application  group  storage  management 

Cache  data 

The  cache  data  setting  determines  if  the  report  data  is  stored  in  disk  cache,  and 
if  so,  how  long  it  is  kept  in  cache  before  it  is  expired.  If  the  cache  data  for  days 
parameter  is  checked,  then  the  search  cache  is  always  selected.  Search  cache 
determines  whether  OnDemand  searches  cache  storage  when  users  retrieve 
documents  from  the  application  group.  When  you  set  the  cache  data  to  No,  you 
can  configure  OnDemand  to  retrieve  existing  documents  from  cache  storage 
while  preventing  new  documents  from  being  copied  to  cache  storage.  If  you 
choose  not  to  store  reports  in  cache,  a  storage  set  that  supports  archive  storage 
must  be  selected. 


Note:  Data  that  is  retrieved  often  should  generally  remain  in  cache  until  it  is  no 
longer  needed  by  90%  of  OnDemand  users. 
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Life  of  data  and  indexes 

The  life  of  data  and  indexes  settings  determine  the  length  of  time  that  report 
data,  indexes  and  resources  are  maintained  in  the  OnDemand  system  before 
they  are  deleted  from  the  application  group.  The  report  data,  indexes  and 
resources  can  be  maintained  indefinitely  if  set  to  never  expire,  or  may  be  kept  for 
up  to  273  years. 


Note:  DSM  maintains  documents  on  disk.  DSM  is  initiated  by  the  STRDSMOND 
command.  DSM  can  delete  documents  after  they  have  exceeded  the  cache 
data  or  life  of  data  periods.  Refer  to  IBM  Content  Manager  OnDemand  for 
iSeries  Common  Server  -  Administration  Guide,  SC27-1 1 61  for  details 
concerning  running  the  STRDSMOND  command. 


Expiration  type 

The  expiration  type  determines  how  report  data,  indexes,  and  resources  are 

expired.  There  are  three  expiration  types: 

►  Load:  If  the  expiration  type  is  load,  an  input  file  at  a  time  can  be  deleted  from 
the  application  group.  The  latest  date  in  the  input  data  and  the  life  of  data  and 
indexes  determines  when  OnDemand  will  delete  the  data.  Data  that  has  been 
stored  in  archive  storage  is  deleted  by  the  storage  manager  based  on  the 
archive  expiration  date.  Load  is  the  recommended  expiration  type. 

►  Segment:  If  the  expiration  type  is  segment,  a  segment  of  data,  which  is  a 
database  file  containing  index  values  for  an  application  group,  at  a  time  is 
deleted  from  the  application  group.  The  segment  must  be  closed  and  the 
expiration  date  of  every  record  in  the  segment  must  have  been  reached.  If 
small  amounts  of  data  are  loaded  into  the  application  group,  and  the 
maximum  rows  value  is  high,  the  segment  may  be  open  for  a  long  period  of 
time  and  the  data  will  not  be  expired  for  the  period. 

►  Document:  If  the  expiration  type  is  document,  a  document  at  a  time  is 
deleted  from  the  application  group.  Storing  with  an  expiration  type  of 
document  causes  the  expiration  process  to  search  through  every  document  in 
the  segment  to  determine  if  the  expiration  date  has  been  reached  resulting  in 
long  processing  times. 
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5.3.3  Advanced  application  group  storage  management 

The  advance  storage  management  settings  (Figure  5-13)  allow  you  to  adjust  the 
size  of  the  load  object  and  to  determine  when  report  data,  indexes,  and 
resources  are  migrated  to  archive  storage. 


Figure  5-27  iSeries  application  group  advanced  storage  management 

Object  size 

The  object  size  parameter  determines  the  size  of  a  storage  object  in  kilobytes. 
OnDemand,  by  default,  segments  and  compresses  stored  data  into  10  MB 
storage  objects.  The  default  10  MB  is  the  recommended  object  size  value. 
Caution  should  be  exercised  when  changing  the  value.  Too  small  or  too  large  of  a 
value  can  have  an  adverse  affect  on  load  performance. 


Note:  The  object  size,  defined  here,  must  be  equal  to  or  larger  than  the  size  of 
the  compressed  storage  objects  defined  in  any  application  assigned  to  the 
application  group. 
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Migrate  data  from  cache 

This  setting  determines  when  documents  and  resources  are  migrated  to  archive 

storage.  A  storage  set  associated  with  a  migration  policy  using  archive  media 

must  be  selected  to  enable  migration  to  archive  storage.  Possible  values  are: 

►  No:  Data  is  never  migrated  from  cache.  This  option  is  greyed  out  when  a 
storage  set  associated  with  archive  storage  is  selected  for  the  application 
group. 

►  When  data  is  loaded:  Data  is  migrated  to  archive  storage  when  the  load 
process  runs  from  one  of  the  store  commands  such  as  ADDRPTOND,  STRMONOND, 
or  arsload. 

►  Next  cache  migration:  Data  is  migrated  to  archive  storage  the  next  time  that 
ASM  is  run  or  when  DSM  is  started  with  the  ASM(*YES)  parameter. 

►  After _ days  in  cache:  Specifies  the  number  of  days  that  data  is  to  remain 

in  cache  only  storage.  After  reaching  the  prescribed  number  of  days  in  cache 
storage,  the  data  is  copied  to  archive  storage  the  next  time  that  ASM  is  run  or 
if  DSM  is  run  with  the  ASM(*YES)  parameter. 


Note:  The  archive  storage  manager  is  started  with  the  STRASMOND  command. 
The  command  should  only  be  run  in  batch.  Refer  to  IBM  Content  Manager 
OnDemand  for  iSeries  Common  Server  -  Administration  Guide,  SC27-1 1 61 , 
for  details  concerning  running  the  STRASMOND  command. 
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Performance 


In  this  chapter  we  discuss  the  ways  in  which  the  various  components  within 
OnDemand  might  be  configured  or  tuned  in  order  to  enhance  performance.  In 
most  cases,  it  is  not  possible  to  give  specific  parameter  values;  however,  we 
provide  broad  concepts  and  recommendations  in  areas  where  tuning  for 
performance  is  possible.  We  provide  performance  guides  for  the  server  and 
OnDemand  Web  Enablement  Kit  (ODWEK)  components,  and  consider  issues 
related  to  specific  data  types  such  as  PDF. 

This  chapter  covers  the  following  topics: 

►  Database 

►  Server  components 

►  ODWEK 

►  Performance  issues  with  certain  data  types 
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6.1  When  performance  tuning  is  necessary 

Due  to  the  way  in  which  OnDemand  integrates  with  a  wide  variety  of  products, 
data  types,  and  operating  systems  spanning  over  many  different  vendors,  it 
should  come  as  no  surprise  to  learn  that  a  standard  installation  of  OnDemand  is 
not  optimized  for  all  of  these  different  environments.  As  part  of  the  installation 
process,  decisions  must  be  made  and  parameter  values  need  to  be  changed 
from  the  default  settings  in  order  to  best  configure  the  product  to  fit  the 
environment  in  which  it  must  operate.  In  many  cases,  it  may  not  be  possible  to 
anticipate  future  demand  and  workload  which  will  be  placed  on  the  system. 
Therefore,  as  requirements  change  over  time,  it  may  be  necessary  to  fine-tune 
the  system  in  order  to  maintain  high  level  of  performance. 

An  example  of  an  area  where  performance  tuning  is  sometimes  required  is  the 
data  loading  process.  The  load  process  which  is  followed  when  the  arsload 
program  is  executed  is  shown  in  Figure  6-1.  This  process  diagram  should  help  in 
determining  which  part  of  the  process  may  be  in  need  of  performance  tuning. 
You  can  see  from  the  diagram  that  within  the  indexing  phase  of  the  overall 
loading  process,  there  are  only  two  key  components  which  can  effect 
performance: 

►  The  indexing  parameters  defined  by  an  OnDemand  administrator 

►  The  report  file 


Figure  6- 1  ARSLOAD  process 

If  you  are  experiencing  poor  performance  during  indexing,  it  is  very  likely  that  one 
of  these  two  areas  is  the  cause  of  the  problem. 
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Also  shown  in  Figure  6-1  is  a  high  level  view  of  the  actual  data  loading  phase  of 
the  overall  load  process.  In  this  phase,  both  the  database  and  the  data  storage 
areas  (such  as  the  cache  and  optical  volumes)  ingest  the  indexes  and  the  data. 
Poor  performance  in  the  loading  phase  is  likely  to  be  caused  by  problems  at 
either  the  database  manager  or  the  storage  manager  level. 

In  order  to  help  you  troubleshoot  any  performance  problems  that  you  may  be 
experiencing  with  OnDemand,  we  have  provided  a  list  of  the  most  common  areas 
where  performance  tuning  may  be  necessary,  cross  referenced  to  the  sections 
within  this  chapter  where  help  and  guidance  can  be  found  (see  Table  6-1). 


Table  6- 1  Performance  troubleshooting  reference 


Problem  area 

Section  to  reference 

Loading  data: 

6.2.4,  “System  management”  on  page  138 

►  Indexing 

6.2.2,  “OnDemand  configuration”  on  page  135 

6.3,  “Performance  issues  based  on  data  type”  on 
page  149 

►  Storing 

6.2.5,  “Storage  management”  on  page  141 

6.2.3,  “Database”  on  page  136 

Retrieving  data: 

See  the  following  subsections: 

►  Searching  for  a 
document 

6.2.3,  “Database”  on  page  136 

6.2.2,  “OnDemand  configuration”  on  page  135 

►  Viewing  a 
document 

6.2.2,  “OnDemand  configuration”  on  page  135 

6.2.6,  “ODWEK  configuration”  on  page  142 

6.3,  “Performance  issues  based  on  data  type”  on 
page  149 

Logon  to  OnDemand 

6.2.2,  “OnDemand  configuration”  on  page  135 

6.2.3,  “Database”  on  page  136 

You  will  notice  that  Table  6-1  specifically  covers  OnDemand  operations  and 
processes  that  may  need  to  be  tuned  to  enhance  performance.  Other  areas, 
such  as  the  underlying  operating  system,  hardware  including  network,  or  even 
contention  with  other  software  running  on  the  same  machine  may  need  to  be 
tuned  for  better  performance.  However,  in  this  chapter,  we  only  deal  with  the 
areas  to  tune  within  OnDemand;  it  is  by  no  means  a  definitive  reference  for  all 
performance  problems  experienced  on  the  machine  where  the  OnDemand 
system  is  installed. 
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6.2  Tuning  OnDemand  to  enhance  performance 

The  following  sections  take  the  various  components  of  an  OnDemand  system 
and  architecture  in  turn  and  provide  guidance  on  parameters  and  configurations 
that  could  be  changed  in  order  to  improve  performance  under  certain 
circumstances.  For  troubleshooting  a  specific  problem  that  you  may  be 
experiencing,  consult  Table  6-1  on  page  133  for  corresponding  section  in  this 
chapter. 


6.2.1  OnDemand  architecture 

From  a  performance  tuning  perspective,  one  of  the  most  significant  features  of 
the  OnDemand  product  is  its  architecture.  As  illustrated  in  Figure  6-2,  there  are 
four  significant  aspects  of  the  OnDemand  architecture: 

►  Library  server:  For  logon,  report  definitions  and  searching  the  database. 

►  Object  server:  For  storage  management  of  data 

►  Client:  Could  be  ODWEK  or  a  Windows  thick  client 

►  Network:  Connecting  these  components  together. 


Figure  6-2  The  OnDemand  architecture 


The  design  of  this  architecture  is  based  on  performance  considerations.  The 
ability  to  separate  the  object  server  from  the  library  server  delivers  two  main 
advantages: 

►  The  ability  to  share  workload  by  dedicating  machines  to  individual  tasks 
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►  The  ability  to  lessen  the  impact  of  retrieving  large  piece  of  data  over  a 
network  that  is  either  slow  or  overloaded 

In  practical  terms,  when  an  OnDemand  architecture  has  distributed  object 
servers,  it  means  that  the  load  job  (arsl  oad)  is  physically  executed  on  the  object 
server  where  you  intend  to  store  the  reports.  As  the  arsl  oad  program  runs,  the 
indexing  is  done  on  the  object  server  and  the  reports  are  loaded  to  the  local 
storage  manager  while  the  indexes  that  have  been  generated  are  sent  to  the 
library  server  to  be  loaded  into  the  database.  A  common  method  of  significantly 
increasing  the  performance  of  loading  data  into  OnDemand  is  to  have  two  object 
servers  running  the  load  program  simultaneously.  For  more  information  on 
running  parallel  load  jobs,  see  “Running  parallel  arsload  jobs”  on  page  139. 

In  addition  to  the  performance  enhancements  in  the  load  process,  there  could 
also  be  improvements  in  document  retrieval  times  if  the  object  servers  are 
distributed  nationally  or  internationally.  A  common  configuration  for  an 
OnDemand  system  which  must  span  large  geographical  areas  is  to  place  an 
object  server  in  each  of  the  main  computer  centers.  With  this  configuration,  users 
can  search  their  documents  from  the  central  library  server,  and  when  they  want 
to  retrieve  a  document,  the  document  is  sent  from  the  object  server  that  is  local 
to  them  (in  network  topology  terms). 

We  should  consider  the  possible  disadvantages  with  this  architecture.  Aside  from 
the  hardware  administration  overhead,  there  are  few  disadvantages  to  having 
multiple  object  servers  within  the  same  data  center;  however,  there  are  some 
issues  to  consider  when  distributing  object  severs  across  geographies. 

►  The  access  to  documents  by  the  users  must  be  carefully  considered  before 
deciding  on  geographically  distributed  object  servers.  If  a  significant  number 
of  users  require  documents  from  object  servers  which  are  not  local  to  them 
(in  networking  terms),  there  are  negative  performance  effects. 

►  Wide  Area  Networks  (WANs)  are  often  less  reliable  then  Local  Area  Networks 
(LANs).  If  object  servers  are  inaccessible  from  the  library  server,  then, 
although  documents  may  be  physically  located  in  the  same  building  as  the 
users,  the  users  will  not  be  able  to  access  the  documents. 


6.2.2  OnDemand  configuration 

The  way  in  which  reports  are  defined,  indexed  and  stored  within  OnDemand 
greatly  influence  the  speed  at  which  OnDemand  can  retrieve  them.  There  are  a 
wide  variety  of  hints  and  tips  for  the  optimum  way  of  defining  reports  within 
OnDemand  which  are  described  in  Chapter  2,  “Administration”  on  page  17.  From 
the  perspective  of  performance,  areas  of  specific  interest  in  that  chapter  are 
“Large  object  support”  on  page  28  and  “Field  information”  on  page  23. 
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OnDemand  system  logging 

An  area  which  is  not  discussed  within  the  Administration  chapter  is  the  effect  of 
system  logging  on  the  overall  performance  of  OnDemand. 

There  are  four  system  logging  event  points  which  can  be  selected  in  order  to 
control  the  messages  that  OnDemand  saves  in  the  system  log.  OnDemand  can 
record  a  message  when  the  following  events  occur: 

►  Login:  A  user  logs  on  a  server. 

►  Logoff:  A  user  logs  off  a  server. 

►  Application  Group  Messages:  A  user  queries  or  retrieves  application  group 
data  and  other  types  of  application  group  events. 

►  Failed  Login:  An  unsuccessful  logon  attempt. 

The  amount  of  logging  that  is  done  on  a  server  is  controlled  in  two  places:  in  the 
System  Parameters  and  in  the  Message  Logging  tab  of  each  of  the  application 
groups  on  the  system.  By  default,  when  you  create  a  new  application  group,  all  of 
the  message  logging  is  turned  on  (except  for  the  database  queries).  Also,  within 
the  system  parameters,  all  four  of  the  system  logging  event  points  listed  earlier 
are  checked  by  default  on  a  standard  OnDemand  installation.  This  means,  by 
default,  an  OnDemand  server  is  in  full  logging  mode.  In  some  cases,  this  can 
have  significant  effects  on  the  system  performance. 

We  recommend  that  unless  you  are  running  the  system  in  a  diagnostic  mode, 
you  should  turn  off  logging  lot  Login  and  Logoff  messages.  If  it  is  a  very  active 
system  with  large  numbers  of  active  users  constantly  logging  in  and  off,  this 
should  improve  the  performance  of  Login  times. 


6.2.3  Database 

OnDemand  creates  a  database  as  part  of  the  installation  process.  Apart  from 
being  able  to  choose  the  location  of  the  database  logs,  there  is  very  little 
opportunity  to  change  the  default  values  used  by  the  database  manager.  For 
example,  in  the  case  of  DB2  UDB,  the  default  parameter  values  are  orientated 
towards  small  machines  with  small  amounts  of  memory.  It  is  not  unusual  for  a 
particular  application  with  a  specialized  use  of  the  database  manager  will  need  to 
alter  some  of  the  default  parameters  in  order  to  optimize  for  performance  in  a 
specialized  environment. 

Database  tuning  efforts  should  be  carefully  monitored  by  a  qualified  DBA  and  are 
highly  dependent  on  individual  system  resources.  The  parameters  listed  below 
should  serve  as  examples  of  areas  within  a  database  configuration  that  can  be 
tuned  if  database  performance  problems  have  been  identified.  In  the  following 
sections,  we  provide  guidance  and  recommendations,  but  we  have  strictly 
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avoided  specifying  actual  values  for  these  parameters  because  each  individual 
tuning  effort  will  be  different  depending  on  the  environment  in  which  the 
database  resides. 

Memory 

It  is  possible  to  allocate  system  memory  to  a  database  application  in  order  to 
gain  more  control  over  the  way  in  which  system  resources  are  allocated.  In  DB2, 
this  memory  allocation  is  called  a  Buffer  pool  and  each  database  has  at  least 
one  of  these.  All  buffer  pools  reside  in  global  memory,  which  is  available  to  all 
applications  using  the  database.  If  the  buffer  pools  are  large  enough  to  keep  the 
required  data  in  memory,  less  disk  activity  will  occur.  Conversely,  if  the  buffer 
pools  are  not  large  enough,  the  overall  performance  of  the  database  can  be 
severely  curtailed  and  the  database  manager  can  become  l/O-bound. 

In  DB2,  the  default  buffer  pool  size  is  1000  (specified  in  4-KB  pages)  which  is 
4  MB.  We  recommend  that  you  increase  this  value  enough  to  reduce  the  risk  of 
becoming  I/O-bound  and  give  the  database  a  decent  buffer  pool  to  work  with. 
Depending  on  the  system  resources,  it  is  beneficial  for  a  production  environment 
to  increase  the  buffer  pool  to  limit  I/O  contention. 

Query  optimization 

This  determines  how  much  effort  the  database  puts  into  optimizing  queries.  A 
high  value  is  often  used  in  a  data  warehousing  environment.  Lower  values  are 
useful  in  On-Line  Transaction  Processing  (OLTP)  type  environment  that  use 
simple  dynamic  queries  which  is  the  case  with  most  of  the  OnDemand  systems. 
Lowering  this  parameter  can  significantly  reduce  CPU  activity  and  prepare  time. 
In  DB2,  for  example,  the  default  query  optimization  class  (DFTQUERYOPT)  is  set  to 
a  value  of  5  which  is  regarded  as  significant  query  optimization. 

Open  database  files 

This  determines  the  maximum  number  of  file  handles  that  can  be  used  for  each 
database  agent.  For  more  information  on  setting  the  number  of  database  agents 
for  OnDemand,  see  6.2.2,  “OnDemand  configuration”  on  page  135. 

In  DB2,  the  parameter  for  setting  the  maximum  number  of  open  database  files 
per  application  is  called  MAXFILOP  and  the  default  value  is  64.  If  opening  a  file 
causes  this  parameter  to  be  exceeded,  some  files  in  use  by  this  agent  must  be 
closed.  Increasing  this  parameter  helps  to  alleviate  the  overhead  of  excessive 
opening  and  closing  files.  The  default  table  space  type  for  an  OnDemand 
installation  is  SMS.  Generally,  SMS  table  spaces  will  need  a  larger  value.  SMS 
table  spaces  have  at  least  one  file  per  database  table  (usually  more). 
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Locking 

Locking  is  the  mechanism  that  the  database  manager  uses  to  control  concurrent 
access  to  data  in  the  database  by  multiple  applications.  The  database  manager 
imposes  locks  to  prohibit  applications  from  accessing  uncommitted  data  and  thus 
protects  data  integrity.  In  DB2,  for  example,  the  parameter  controlling  this  is 
LOCKLIST  and  the  default  is  100  (specified  in  4KB  pages).  Setting  the  lock  list 
parameter  sufficiently  high  helps  to  prevent  lock  escalation.  Lock  escalation  are 
the  conversion  of  record  locks  to  table  locks. 

Transaction  logs 

The  database  transaction  logs  should  be  placed  on  separate  physical  disk(s) 
from  the  database  in  order  to  avoid  contention  with  the  data  I/O.  In  addition, 
physically  separating  the  database  transaction  logs  from  the  database  means 
that  in  the  event  of  a  media  failure,  the  logs  will  not  be  lost  with  the  database  and 
recovery  will  be  possible.  The  log  disks  must  be  protected  to  ensure  database 
consistency,  and  due  to  the  high  write  content,  mirroring  is  typically  preferred 
over  RAID-5.  Notice  that  there  is  performance  hit  to  mirroring. 

DB2  parallelism 

Parallelism  within  DB2  is  designed  for  best  performance  when  running  few,  but 
complex,  number-crunching  type  queries.  OnDemand  submits  a  very  large 
number  of  simple  queries  for  user  logon  and  folder  searches.  The  overhead 
generated  by  DB2  parallelism  can  impact  server  performance  in  an  OnDemand 
environment. 

To  check  the  setting  for  parallelism,  do  the  following: 

1 .  From  a  DB2  command  prompt,  enter  the  following  command 
GET  DATABASE  MANAGER  CONFIGURATION 

2.  Check  the  parameter  I NTRA_PARALLEL  = 

3.  If  this  is  set  to  YES,  change  it  to  No  by  enter  the  following  command: 

UPDATE  DATABASE  MANAGER  CONFIGURATION  USING  INTRA_PARALLEL  NO 

4.  Restart  DB2  for  the  change  to  take  effect. 

6.2.4  System  management 

The  recommendations  and  guidance  in  this  section  fall  under  the  category  of 
system  management  because  the  majority  of  them  are  outside  of  the  control  of 
the  OnDemand  product  code. 
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Running  parallel  arsload  jobs 

A  common  misconception  with  OnDemand  is  that  because  there  is  a  single  load 
program  for  loading  data  into  OnDemand  (arsload),  you  may  only  have  one  of 
these  load  jobs  running  at  any  one  time.  This  is  not  true.  Depending  on  the 
resources  of  the  machine  (memory,  CPU,  and  DASD),  it  is  possible  to  run 
multiple  arsl  oad  jobs  simultaneously  in  order  to  improve  the  overall  performance 
of  the  load  process.  This  is  especially  true  in  an  architecture  where  there  are 
multiple  object  servers  distributed  onto  different  physical  machines. 

Our  key  recommendation  with  regard  to  running  multiple  arsload  jobs  is  that 
unless  the  system  has  a  distributed  object  server  architecture,  try  not  to  start  all 
of  the  load  jobs  at  the  same  time.  If  you  do  start  multiple  arsload  jobs 
simultaneously,  you  may  still  get  a  performance  benefit;  but  if  you  stagger  the 
load  jobs,  then  each  of  them  will  be  at  a  different  phase  of  the  load  process, 
which  will  maximize  performance  due  to  less  I/O  contention  in  the  database  and 
in  cache  storage  volumes.  In  order  to  clarify  this  point  further,  please  see 
Figure  6-1  on  page  132,  which  illustrates  the  different  phases  in  the  load 
process. 

The  ARS_NUM_DBSRVR  parameter 

This  parameter  is  set  in  the  ars .  cfg  file  and  it  determines  the  number  of  DB2 
database  agents  that  are  launched  automatically  when  the  OnDemand  server  is 
started.  Under  normal  circumstances,  each  connection  to  the  database  requires 
a  database  agent  which  is  launched  whenever  a  database  connection  is 
requested.  However,  starting  several  database  agents  which  remain  active  and 
waiting  for  connection  requests  can  enhance  performance  because  there  is  no 
time  spent  initializing  and  then  closing  the  agents. 

We  recommend  that  for  systems  running  several  large  load  jobs  in  parallel,  or  for 
systems  that  have  large  numbers  of  very  active  users,  you  should  increase  this 
parameter  from  the  default  of  4.  For  more  detailed  guidance,  refer  to  Appendix  A, 
in  IBM  Content  Manager  OnDemand  for  Multiplatforms  -  Installation  and 
Configuration  Guide  for  UNIX  Servers,  GC27-0834. 

File  systems  on  UNIX 

During  the  installation  and  setup  of  OnDemand,  one  of  the  tasks  is  the  creation 
of  file  systems  needed  to  contain  the  various  OnDemand  components.  This  task 
is  described  under  “Disk  storage  devices  on  a  UNIX  server”,  in  Chapter  3,  “Disk 
storage  requirements”,  in  the  manual,  IBM  Content  Manager  OnDemand  for 
Multiplatforms  -  Installation  and  Configuration  Guide  for  UNIX  Servers, 
GC27-0834.  Table  14,  “Disk  storage  group  for  a  large  organization”,  in  this  guide 
gives  an  example  of  the  file  systems  which  may  need  to  be  created  for  a  large 
OnDemand  system.  More  importantly,  it  gives  an  example  of  how  to  organize 
these  file  systems  in  order  to  optimize  performance. 
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The  reason  this  is  so  important  is  that  I/O  contention  is  one  of  the  most  common 
causes  of  performance  problems. 

For  performance  reasons,  when  the  OnDemand  file  systems  are  created,  the 
following  components  should  not  be  on  the  same  physical  media: 

►  The  Cache  filesystem 

►  The  Database  filesystem 

►  The  Primary  logs  filesystem 

►  The  Secondary  logs  filesystem 

►  The  Load  /  indexing  filesystem 

►  The  OnDemand  temporary  space  filesystem 

Operating  system  performance 

With  the  wide  variety  of  platforms  that  OnDemand  supports,  there  comes  an 
even  wider  variety  of  performance  issues  specific  to  the  individual  architecture  of 
these  underlying  operating  systems.  Depending  on  the  operating  system  itself, 
there  are  a  number  of  different  tools  and  methods  for  monitoring  and  tuning  the 
operating  system.  If  you  are  experiencing  performance  problems  and  you  believe 
that  you  have  followed  all  of  the  guidance  available  for  configuring  OnDemand, 
make  sure  that  you  check  with  the  vendor  of  your  operating  system  to  confirm 
that  you  are  at  the  latest  service  pack  or  maintenance  level  and  that  there  are  no 
known  problems  with  performance  at  this  level. 


Note:  A  virtual  memory  leak,  discovered  in  AIX  4.3.3,  is  described  in  APAR 
IY15250.The  problem  is  fixed  by  applying  maintenance  level  9,  and  by  tuning 
the  MINFREE  and  MAXFREE  parameters.  This  AIX  performance  problem  is  a  good 
example  regarding  the  necessity  to  check  operating  system  maintenance  for 
performance  fixes. 


Network 

OnDemand  has  various  features  such  as  compression  and  large  object  support 
which  minimize  the  impact  of  retrieving  large  quantities  of  information  from  the 
server  over  a  network.  However,  network  performance  and  topology  can  often  be 
the  bottleneck  in  a  system  architecture,  especially  when  the  data  retrieved  is 
large  image  files  which  can  not  be  compressed.  Guidance  for  tuning  the 
OnDemand  environment  to  cater  for  the  network  bandwidth  which  is  in  place  can 
be  found  in  6.2.1 ,  “OnDemand  architecture”  on  page  1 34,  6.2.2,  “OnDemand 
configuration”  on  page  1 35  and  6.3,  “Performance  issues  based  on  data  type”  on 
page  149. 
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6.2.5  Storage  management 

Regardless  of  platforms,  storage  management  with  OnDemand  can  be  divided 
into  two  areas:  cache  storage  managed  by  OnDemand  and  archive  media 
managed  by  an  external  product  such  as  TSM,  OAM,  VSAM  or  ASM.  In  terms  of 
storage  management,  one  of  the  key  performance  features  with  OnDemand  is 
the  ability  to  load  data  to  archive  media,  but  simultaneously  retain  a  temporary 
cached  copy  of  the  most  recent  archived  data  on  fast  access  media  (such  as 
DASD).  The  expiration  and  management  of  this  cached  copy  of  the  data  is  done 
by  OnDemand  so  that  after  a  certain  predefined  period  has  elapsed,  the  data  is 
removed  from  cache  and  the  only  remaining  copy  with  be  held  on  the  much 
slower  archive  media  managed  by  either  TSM,  OAM,  VSAM  or  ASM  depending 
on  the  platform. 

If  performance  problems  are  encountered  at  the  storage  manager  level,  the  issue 
is  almost  always  related  to  the  inherent  qualities  of  the  slower  media  types  (such 
as  optical  platters  and  tape  volumes)  or  the  way  in  which  the  archive  media 
manager  is  configured.  To  ensure  that  it  is  not  the  OnDemand  configuration  done 
by  the  administrator  that  is  causing  the  slower  performance  from  the  storage 
manager,  also  see  6.2.2,  “OnDemand  configuration”  on  page  135. 

Physical  media  /  library  issues 

In  order  to  troubleshoot  possible  performance  problems  with  physical  media  and 
library  devices,  it  is  important  to  understand  the  basic  principles  behind  the 
working  of  these  devices.  Typically,  a  library  device  containing  either  optical  or 
tape  volumes  will  have  a  certain  number  of  drives.  A  drive  is  an  area  in  the  library 
where  a  volume  is  placed  in  order  to  be  read  from.  If,  for  example,  an  IBM  3995 
Optical  jukebox  has  six  drives  and  all  of  these  drives  are  busy  reading  from 
volumes,  then  the  next  time  a  request  is  made  for  data  to  be  read  from  another 
volume,  that  request  is  queued. 

This  example  is  typical  of  a  situation  where  data  is  being  loaded  into  OnDemand 
at  the  same  time  that  users  are  active  on  the  system  and  retrieving  documents 
from  OnDemand.  The  most  common  way  to  avoid  this  performance  problem  is  to 
schedule  load  jobs  at  times  when  the  system  is  not  in  use  by  the  user  community, 
so  that  the  load  can  have  full  use  of  all  of  the  drives  in  the  library  to  load  the  large 
quantities  of  data  that  are  necessary  during  this  process. 
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Mount  retention  of  optical  /  tape  volumes 

Mount  retention  determines  how  long  in  minutes  to  retain  idle  storage  volumes  in 
a  drive  before  dismounting.  This  parameter  can  improve  response  time  by 
leaving  previously  mounted  volumes  online.  A  low  number  is  recommended  for 
high-access  systems.  However,  the  setting  of  this  mount  retention  value  will 
depend  on  the  way  in  which  archived  data  is  searched  upon.  For  example,  if  a 
number  of  users  are  all  retrieving  data  from  a  similar  time  period,  then  it  is  likely 
that  this  data  will  be  on  the  same  physical  volume.  Leaving  the  volume  mounted 
in  the  drive  between  retrievals  will  improve  retrieval  times,  because  time  is  not 
spend  finding  and  mounting  the  volume  onto  the  drive  before  the  data  can  be 
read. 

In  TSM,  the  mount  retention  of  optical  or  tape  volumes  is  set  when  defining  the 
device  class.  Example  6-1  is  an  extract  from  the  archive. mac  which  is  shipped 
with  a  standard  installation  of  OnDemand  for  Multiplatforms.  The  archi  ve.mac  file 
is  an  extremely  useful  tool  to  use  in  order  to  configure  a  TSM  environment  with 
OnDemand.  For  more  information  about  storage  management  with  TSM,  OAM 
(for  zSeries)  and  ASM  (for  iSeries),  see  Chapter  5,  “Storage  management”  on 
page  85 

Example  6-1  Setting  mountretention  in  TSM 

def  devclass  odlibO  devtype=opti cal  format=1300MB  library=archlibO 
mountl imit=2  mourtretenti on=10  estcapaci ty=1309M 


6.2.6  ODWEK  configuration 

The  OnDemand  Web  Enablement  Kit  (ODWEK)  has  a  number  of  functional 
components  which  can  be  configured  within  your  environment  in  order  to 
optimize  thin  client  search  and  retrieval  from  an  OnDemand  server.  For  more 
information  about  the  ODWEK  architecture,  APIs  and  installation  see  Chapter  8, 
“Installing  and  customizing  ODWEK”  on  page  171. 

The  ODWEK  cache 

One  of  the  performance  enhancing  features  of  ODWEK  is  the  ability  to  cache 
session  information  and  even  documents  on  the  Web  server  machine.  However, 
in  order  to  ensure  that  you  are  optimizing  ODWEK  performance  while  still 
minimizing  the  amount  of  DASD  required  for  the  ODWEK  cache,  it  is  important 
that  it  is  configured  and  sized  correctly. 

In  order  to  know  how  to  size  the  cache,  it  is  important  to  understand  what  type  of 
information  and  data  files  are  stored.  Table  6-2  describes  the  different  types  of 
data  that  can  be  stored  in  the  cache  as  well  as  explaining  how  many  of  these 
different  data  files  are  created  for  each  user. 
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Table  6-2  Cached  data  description 


Description 

Frequency 

File  Extension 

Server  Name 

1  for  each  user 

SRV 

Folder  Names 

1  for  each  user 

FNM 

Folder  search  fields 

1  for  each  folder  for  each 

user 

FLD 

AFP  resources 

1  for  each  resource 

RES 

Documents 

1  for  each  document 

DOC 

OnDemand  internal  file 

1  for  each  document 

IDOC 

Line  data  document 

1  for  each  line  data  doc 

ASC 

It  is  impossible  to  estimate  a  generic  size  or  growth  rate  for  all  ODWEK  systems 
due  to  the  fact  that  the  numbers  of  users,  data  types,  folders  and  AFP  resources 
vary  enormously  from  one  installation  to  another.  However,  it  is  possible  to  offer 
guidance  which  can  be  followed  given  information  about  the  individual 
environment. 

ODWEK  cache  sizing  process 

Despite  the  variability  of  data  produced  in  the  cache,  it  is  possible  to  apply  the 
following  simple  process  in  order  to  size  the  ODWEK  cache: 

1 .  Install  and  test  ODWEK  based  on  the  instructions  in  ODWEK  Installation  and 
Configuration  Guide. 

2.  In  the  arswww. ini  file,  ensure  that  the  Cache*  parameters  (Example  6-2)  are 
set: 

Example  6-2  Cache  parameters 

[configuration] 

Language=ENU 

Tempi ateDi r=/home/httpd/docs/templ ates 

ImageDi r=/images 

Appl etDi r=/appl ets 

TempDi r=/odwek/temp 

CacheDi r=/odwek/cache 

CacheSize=10 

CacheMi nThreshol d=40 

CacheMaxThreshol d=80 

CacheDocs=0 

CacheUserIDs=web,demo 
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3.  After  testing  the  installation  there  should  be  a  number  of  files  in  the  location 
described  by  the  CacheDi  r  parameter.  Delete  all  of  these  files  so  that  the 
cache  is  empty. 

4.  Based  on  knowledge  of  the  use  of  OnDemand  by  the  user  community,  logon 
to  OnDemand  via  ODWEK  and  perform  a  number  of  search  and  retrieve 
operations  from  a  typical  set  of  folders  and  different  data  types. 

5.  Examine  the  files  residing  in  the  cache  directory.  You  should  see  several  files 
and  the  reason  for  the  existence  of  the  files  shown  is  described  in  Table  6-2. 

For  example  in  the  Figure  6-3,  you  can  see  that  the  admin  user  logged  on  to 
OnDemand  via  ODWEK  and  opened  three  folders  (Credit  Card  Statements, 
Letters  and  TWS  Job  Reports). 


Figure  6-3  The  ODWEK  cache 

6.  Figure  6-3  also  shows  an  example  of  the  overall  size  of  the  cache  after  doing 
this  operation  (63.4KB).  If  you  are  satisfied  that  this  is  a  typical  search,  then 
the  collective  size  of  these  files  must  be  multiplied  by  the  number  of 
concurrent  users  expected  to  access  this  ODWEK  system. 

7.  We  recommend  that  you  also  add  25%  to  the  value  from  step  6  for 
contingency. 
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Attention:  You  will  note  from  Example  6-2  that  the  CacheDocs  parameter  was 
set  to  0;  therefore,  only  folder,  server  and  resource  information  was  collected 
in  the  cache  illustrated  in  Figure  6-3. 


Caching  documents 

If  you  intend  to  cache  documents  that  are  retrieved  from  OnDemand  in 
conjunction  with  the  session  information  and  resources,  then  it  is  far  more  difficult 
to  estimate  an  optimum  cache  size.  You  can  follow  the  same  process  as  above; 
however,  be  aware  of  the  following  factors: 

►  Documents  are  typically  much  larger  than  session  information,  and  so  when 
sizing  a  cache  to  include  documents,  you  will  find  that  much  more  space  is 
required. 

►  If  the  likelihood  of  many  users  frequently  viewing  the  same  documents  is 
high,  then  caching  documents  could  be  beneficial  as  ODWEK  will  not  need  to 
retrieve  the  documents  from  OnDemand  many  times. 

►  If  the  cache  size  is  too  large,  then  it  may  take  ODWEK  more  time  to  check  the 
cache  to  see  if  a  document  is  present  than  to  retrieve  the  document  from 
OnDemand.  To  avoid  this,  we  would  recommend  the  cache  size  be  no  larger 
than  200  MB. 

►  If  the  network  is  slow  or  overloaded  between  the  OnDemand  server  and  the 
Web  server,  then  caching  documents  may  alleviate  this  problem. 

The  ODWEK  cache  is  one  of  the  main  areas  for  tuning  ODWEK  in  order  to 
optimize  performance  in  your  environment.  Considered  and  deliberate  sizing  of 
the  cache  can  see  significant  performance  benefits. 

Servlet  verses  CGI 

As  described  on  Section  “Deploying  the  CGI  program”  and  Section  “Deploying 
the  servlet”,  in  Chapter  2,  “Installation  and  Configuration”,  in  IBM  Content 
Manager  OnDemand  -  Web  Enablement  Kit  Installation  and  Configuration  Guide, 
SC27-1000,  there  are  two  protocols  that  you  can  optionally  choose  in  order  to 
control  ODWEK: 

►  CGI  program:  The  CGI  program  runs  against  an  HTTP  server,  such  as  the 
IBM  HTTP  Server. 

►  Java  servlet:  The  servlet  runs  on  a  Java-enabled  HTTP  server  with  a  Java 
application  server,  such  as  the  IBM  WebSphere  ™  Application  Server. 

From  a  performance  perspective,  we  recommend  the  servlet  implementation  of 
ODWEK.  The  reason  for  this  is  that  the  CGI  program  is  called  by  the  Web  Server 
program  each  time  an  operation  is  submitted  by  a  user  which  involves 
connecting  to  the  OnDemand  server.  When  the  CGI  program  is  executed,  it  must 
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load  the  shared  libraries  into  memory  and  this  memory  must  be  allocated  to  each 
of  the  CGI  processes  that  have  been  launched.  In  contrast,  the  servlet  need  only 
load  the  shared  libraries  into  memory  the  first  time  it  is  activated  per  session. 
Subsequent  users  that  submit  operations  to  OnDemand  via  the  servlet  should 
experience  faster  response  times  than  the  CGI. 

Web  server  architecture 

A  common  method  of  workload-balancing  a  system  is  to  distribute  components 
of  the  architecture  across  multiple  physical  machines.  A  good  example  of  this 
can  be  demonstrated  by  the  OnDemand  architecture  which  is  described  in  6.2.1 , 
“OnDemand  architecture”  on  page  134. 

When  ODWEK  is  used  as  the  viewing  technology  for  OnDemand,  the  Web 
server  must  be  considered  as  one  of  those  components  within  the  architecture  to 
separate  from  the  machine  that  the  OnDemand  server  is  running  on.  If  the  Web 
server  and  the  OnDemand  server  are  separated  onto  dedicated  machines,  then 
this  should  significantly  improve  overall  system  performance. 

It  is  also  possible  to  have  multiple  Web  servers.  This  is  necessary  if  you  have  an 
OnDemand  architecture  with  multiple  distributed  object  servers  where  typically 
there  would  be  a  Web  server  (with  ODWEK  installed  on  it)  in  close  proximity  to 
each  of  the  object  servers.  With  this  configuration,  ODWEK  users  can  benefit 
from  the  fast  retrieval  of  their  documents  from  object  server  in  their  location. 


Tip:  With  ODWEK,  the  OnDemand  object  server  must  deliver  the  object  via 
the  Web  server.  If  you  have  multiple  object  servers  which  may  be  distributed 
throughout  your  enterprise  but  only  a  single  Web  server,  then  all  objects  must 
be  delivered  through  that  Web  server.  You  will  not  be  utilizing  the  strengths  of 
the  fast  document  retrieval  from  the  distributed  object  servers. 


Debug  /  logging  turned  off 

For  the  purposes  of  auditing  operations  and  debugging  any  problems  discovered 
with  ODWEK,  there  is  a  debug  and  logging  tool  which  can  be  activated.  The 
parameters  in  Example  6-3  produce  a  file  called  arswww.log  in  the  specified 
directory.  This  is  an  excellent  tool  for  debug  purposes  but  for  performance 
reasons,  this  logging  must  be  turned  of  in  a  production  environment.  This  is  done 
by  setting  the  1  og  parameter  to  0 . 

Example  6-3  Logging  in  ODWEK 

[DEBUG] 

log=l 

logdir=D:\temp 
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User  IDs 

For  OnDemand  installations  intended  for  use  only  by  internal  employees,  the 
most  common  use  of  the  OnDemand  user  ID  is  for  each  individual  who  requires 
access  to  OnDemand  to  have  a  unique  ID.  Typically  within  an  internal 
environment,  there  is  an  easily  defined  user  who  can  be  categorized  into 
OnDemand  groups  based  on  department  or  job  responsibility.  Under  these 
circumstances,  ODWEK  is  simply  used  as  a  thin  client  access  technology  to  the 
OnDemand  server  and  is  for  internal  use  only. 

However,  the  majority  of  ODWEK  installations  are  intended  as  a  method  of 
externalizing  access  to  documents  stored  in  OnDemand  to  a  public  Internet  site. 
Depending  on  the  nature  of  the  content  which  you  intend  to  deliver  to  a  Web  site, 
it  may  be  far  more  difficult  to  define  each  individual  user  who  may  attempt  to 
access  the  information.  Also,  more  importantly  is  that  from  a  performance  and 
ease  of  administration  perspective,  you  may  not  need  or  want  to  define  each 
person  who  requires  access  to  information  of  an  individual  OnDemand  account. 

Figure  6-4  describes  the  process  which  is  followed  within  ODWEK  when  a  user 
with  their  own  OnDemand  user  ID  retrieves  a  document.  In  reality,  this  process 
will  be  followed  each  time  the  user  issues  a  new  logon;  for  subsequent  searches 
after  a  logon,  there  will  be  ODWEK  caching  for  folder  lists  and  folders  as 
described  in  “The  ODWEK  cache”  on  page  142.  What  Figure  6-4  shows  is  a 
simple  example  of  an  interaction  between  a  user  and  OnDemand  which  involves 
four  requests  submitted  by  the  user  via  ODWEK  and  four  replies  submitted  by 
OnDemand  via  ODWEK. 
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We  recommend  that  you  optimize  the  configuration  shown  in  Figure  6-4  by  define 
a  small  subset  of  users  within  OnDemand  and  force  all  Web  users  to  access 
OnDemand  via  this  subset  of  OnDemand  user.  The  main  advantage  of 
channeling  large  numbers  of  Web  requests  through  a  small  number  of  users  is 
that  ODWEK  is  far  more  efficient  at  managing  a  small  number  of  highly  active 
users  than  very  large  number  of  idle  users.  Figure  6-5  shows  the  significant 
decrease  in  communication  between  ODWEK  and  the  OnDemand  server  when  a 
single  user  ID  is  used  as  a  channel  for  multiple  user  requests. 

The  configuration  illustrated  in  Figure  6-5  is  typically  implemented  with  the  use  of 
a  custom  Web  application  which  the  public  Web  user  will  use  in  order  to  obtain 
information  stored  in  OnDemand.  This  Web  application  will  authenticate  the 
identity  of  the  Web  user  and  control  the  access  that  they  have  to  OnDemand. 
Rather  than  using  unique  user  IDs,  the  Web  application  will  access  OnDemand 
via  a  common  user  ID  (or  a  small  subset  of  user  IDs)  and  retrieve  the  required 
information  on  the  Web  users’  behalf  by  constructing  queries  dynamically  and 
submitting  them  to  ODWEK  for  processing.  By  using  this  technique,  not  only  is 
performance  of  OnDemand  and  ODWEK  optimized;  but  also  an  added  layer  of 
Web  security  is  put  in  place  to  protect  access  to  the  OnDemand  server. 


multiple  users  use  the  same  ID 


ODWEK 


Cache 


Folder 

List 


Figure  6-5  ODWEK  with  single  user  ID  access 
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If  ODWEK  is  used  to  deliver  content  to  a  public  Web  site,  the  configuration 

illustrated  in  Figure  6-5  is  recommended  for  the  following  reasons. 

►  There  would  be  a  substantial  decrease  in  the  workload  of  OnDemand 
user/system  administrators  due  to  a  significantly  smaller  user  community. 

►  Unnecessary  work  by  the  Web  users  to  create  OnDemand  user  accounts 
could  be  avoided. 

►  There  would  be  a  substantial  decrease  in  the  size  of  the  ODWEK  cache. 

►  Communication  between  ODWEK  and  the  OnDemand  server  could  be 
decreased  by  a  factor  of  2  and  therefore  improving  response  times 
experience  by  the  users. 


6.3  Performance  issues  based  on  data  type 

This  final  section  on  performance  describes  issues  related  to  individual  data 
types  which  can  have  significant  effects  on  the  overall  performance  of 
OnDemand.  Some  of  these  issues  can  be  addressed  by  selecting  (or 
deselecting)  certain  functions  and  features  within  OnDemand.  Some  of  the 
issues  discussed  below  can  only  be  addressed  by  changing  the  way  in  which  the 
data  is  produced  from  the  source. 

6.3.1  PDF  data 

Portable  Document  Format  (PDF)  data  is  an  increasingly  common  data  type 
which  can  be  archived  within  OnDemand.  The  key  advantages  of  using  this  data 
type  as  a  document  format  are  as  follows: 

►  It  is  a  read-only  format  that  does  not  require  any  external  resources  such  as 
images  or  fonts.  It  is  self  contained. 

►  The  viewer  for  PDF  is  free  to  download  from  the  Adobe  Web  site  and  the 
browser  plug-ins  for  PDF  is  also  freely  available. 

From  a  performance  standpoint,  the  issue  that  commonly  arises  with  the  PDF 
data  type  is  illustrated  in  Figure  6-6.  As  we  have  stated  above,  one  of  the  main 
advantages  of  PDF  data  is  its  self  contained  nature;  however,  when  archiving  this 
data,  it  is  also  one  of  the  main  disadvantages. 
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PDF  Report  file  Indexed  PDF  Report  file 


Converted  to 

c^7 


Figure  6-6  PDF  architecture 

When  PDF  is  produced,  resources  such  as  images  and  custom  fonts  are  placed 
in  the  data  stream  once  (usually  at  the  top)  and  then  referenced  many  times  from 
within  the  PDF  file.  If  for  example,  a  large  report  is  produced  which  might  be  a 
collection  of  many  small  documents,  then  the  advantage  is  that  only  one  copy  of 
the  resources  are  required.  However,  in  order  for  OnDemand  (or  any  archive 
product)  to  split  this  report  into  a  collection  of  self  contained  documents,  the 
resources  must  be  copied  and  placed  within  each  of  the  smaller  documents.  The 
effect  of  doing  this  is  illustrated  in  Figure  6-6.  It  is  not  uncommon  for  the  sum  of 
the  individual  documents  to  be  many  times  larger  than  the  original  report. 

This  issue  can  create  a  variety  of  problems  during  the  load  process: 

►  If  this  increase  in  file  size  has  not  been  anticipated,  the  temporary  space  used 
during  indexing  could  be  too  small  and  the  load  will  fail. 

►  The  PDF  indexer  has  a  maximum  file  size,  4  GB,  that  it  can  be  loading  to 
OnDemand.  If  the  resulting  PDF  file  which  the  indexer  produces  is  larger  than 
this  maximum  file  size,  then  the  load  will  fail. 
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The  most  common  cause  for  expediential  increases  in  the  PDF  file  to  be  loaded 
into  OnDemand  is  the  inclusion  of  custom  fonts  into  the  PDF  data.  For  a  small 
two  to  three  page  document,  custom  fonts  typically  make  up  the  majority  of  the 
overall  size  of  a  document  if  they  are  included  in  the  data  stream. 

The  primary  aim  of  this  section  is  to  increase  awareness  of  the  issues  with 
archiving  PDF  data.  Our  recommendation  is  that  if  PDF  data  is  the  only  format 
possible  to  archive  your  data,  then  wherever  possible,  use  the  base  14  fonts 
which  do  not  need  to  be  included  in  the  data.  More  information  on  the  PDF  data 
stream  and  the  font  issues  can  be  found  in  Chapter  7,  “PDF  indexing”  on 
page  157. 


6.3.2  Line  data 

Line  data  (ASCII  or  EBCDIC  text  based  reports)  are  the  most  common  type  of 
data  stored  in  OnDemand.  The  type  of  line  data  that  we  will  discuss  here  is  a 
special  form  of  transaction  style  report  where  it  is  necessary  to  search  on  a  value 
that  appears  on  every  line  of  the  report.  This  transaction  data  typically  has  a 
transaction  number  which  appears  on  every  line  and  must  be  sorted  either  by 
column  or  row  and  either  ascending  or  descending. 

When  indexing  transaction  data,  if  each  transaction  number  from  each  line  of  the 
report  was  treated  as  a  database  index  such  as  date  or  customer  name,  then  the 
database  would  grow  to  be  extremely  large  in  just  a  short  period  of  time. 
OnDemand  has  a  special  type  of  field  for  transaction  data  which  is  illustrated  in 
Figure  6-7  as  the  boxes  data  on  the  left  of  the  screen  display. 
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Figure  6-7  Transaction  data  in  the  graphical  indexer 

The  transaction  data  field  selects  the  first  and  last  values  from  a  group  of  pages 
and  only  these  group  level  values  are  inserted  into  the  database.  OnDemand 
queries  the  database  by  comparing  the  search  value  entered  by  the  user  to  two 
database  fields,  the  beginning  value  and  the  ending  value.  If  the  value  entered 
by  the  user  falls  within  the  range  of  both  database  fields,  OnDemand  adds  the 
item  to  the  document  list. 

From  a  performance  perspective,  using  the  transaction  data  field  for  transaction 
style  line  data  optimizes  indexing  performance  by  significantly  reducing  the 
number  of  index  values  to  be  inserted  into  the  database.  This  means  that  loading 
and  retrieving  these  extremely  large  reports  is  significantly  faster  and  the 
OnDemand  database  is  many  times  smaller. 
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6.3.3  AFP  data 

Advanced  Function  Presentation  (AFP)  data  is  a  multi-part  data  type.  This 
means  that  in  addition  to  the  variable  data  itself,  there  are  also  external 
resources  such  as  images,  fonts,  and  logos  which  are  referenced  by  the  AFP 
data  stream.  When  OnDemand  stores  AFP,  the  resources  are  also  archived. 
When  the  data  is  viewed,  the  referenced  resources  are  displayed. 

It  is  a  common  misconception  that  if  fonts  are  collected  when  the  data  is  loaded, 
that  they  are  available  for  viewing  in  the  Windows  client.  The  fact  is  Windows 
does  not  recognize  AFP  fonts.  It  is  not  possible  to  use  these  fonts  even  if  they  are 
sent  to  the  client  as  part  of  the  resource.  Windows  clients  require  a  mapping  from 
AFP  fonts  to  ATM  or  TTFonts.  OnDemand  provides  this  mapping  for  most 
standard  fonts.  For  more  information  on  mapping  custom  fonts,  refer  to  IBM 
Content  Manager  OnDemand  -  Windows  Client  Customization  Guide  and 
Reference,  SC27-0837. 

One  possibly  useful  implementation  of  storing  fonts  with  the  resource  group  is 
where  server  reprint  is  necessary.  If  the  fonts  are  stored  with  the  resource  group, 
they  can  be  retrieved  from  OnDemand  and  used  by  AFP  printers.  However,  if 
fonts  are  collected,  they  are  also  sent  to  the  client  as  part  of  the  resources  group 
and  then  discarded.  Storing  the  fonts  with  the  resource  group  only  serves  to 
increase  network  traffic  when  transferring  the  resource  to  the  PC.  A  more 
practical  option  for  server  printing  is  to  store  the  font  in  a  fontlib  and  keep  only  the 
reference  (path)  to  the  fontlib.  As  long  as  the  font  is  accessible  on  the  server, 
PSF/InfoPrint  does  not  need  the  font  to  be  inline  (stored  in  the  resource  group). 
Using  this  approach  also  allows  all  AFP  data  referencing  the  font  to  use  the 
single  instance  of  the  font  without  redundant  inline  storage. 

Figure  6-8  shows  the  panel  in  the  application  where  you  can  select  what 
resources  to  collect.  We  recommend  that  unless  reprints  to  AFP  printers  with 
100%  fidelity  is  a  requirement,  then  fonts  should  not  be  collected. 
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Figure  6-8  Collecting  AFP  fonts 

The  iSeries  system  does  not  collect  the  fonts,  and  it  does  not  give  the 
administrator  that  option.  The  Indexer  Properties  >  Resource  Information  dialog 
is  not  available  to  the  iSeries  administrator.  If  reprinting  to  an  AFP  printer,  the 
fonts  must  be  available  on  the  iSeries  server,  or  font  substitution  is  done. 

Image  data 

In  order  to  optimize  performance  with  storing  and  retrieving  image  formats  such 
as  TIFF,  GIF  and  JPEG,  we  recommend  that  you  do  not  compress  the  data  as 
the  file  sizes  may  actually  increase.  In  order  to  turn  compression  off,  select 
option  Disable  from  the  Load  Information  tab  within  the  application.  This  is 
shown  in  Figure  6-9. 
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Figure  6-9  Disabling  compression 

Notice  that  there  are  two  options  which  turn  off  data  compression: 

►  Disable:  OnDemand  does  not  compress  the  input  data.  Choose  this  option 
when  the  input  data,  such  as  PDF  and  compressed  TIFF,  is  already 
compressed.  Documents  are  uncompressed  by  the  appropriate  viewer  on  the 
client  (for  example,  Acrobat  Reader). 

►  None:  OnDemand  does  not  compress  the  input  data  when  loading  it  into  the 
system.  When  the  user  selects  a  document  for  viewing,  OnDemand 
compresses  the  document  before  transmitting  it  over  the  network  and  will 
uncompress  the  document  at  the  client. 
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In  this  chapter  we  describe  PDF  indexing  from  a  practical  standpoint,  with 
specific  reference  to  the  issues  surrounding  the  archival  of  the  PDF  data  stream. 
We  discuss  the  process  of  graphically  indexing  PDF  and  any  differences 
between  the  respective  platforms  in  this  area. 

The  following  topics  are  covered: 

►  PDF  data  stream  issues  and  concepts 

►  PDF  indexer 

►  PDF  indexing  on  z/OS 
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7.1  Getting  started 

The  architectural  definition  of  Portable  Document  Format  (PDF)  as  produced  and 
designed  by  Adobe  Systems,  is  as  follows: 

THE  ADOBE  PORTABLE  DOCUMENT  FORMAT  (PDF)  is  a  file  format  for- 
representing  documents  in  a  manner  independent  of  the  application  software, 
hardware,  and  operating  system  used  to  create  them  and  of  the  output  device  on 
which  they  are  to  be  displayed  or  printed. 

(Section  2,  “Overview”,  in  PDF  Reference,  by  Adobe  Systems  Incorporated). 

The  following  sections  serve  as  an  introduction  to  the  technical  concepts  and 
architecture  behind  the  PDF  data  type  in  order  to  help  you  understand  potential 
issues  in  indexing  this  data. 


7.1.1  What  is  the  Portable  Document  Format? 

In  simple  terms,  PDF  is  a  data  type  or  file  format  which  is  independent  of  the 
platform  on  which  it  is  created.  A  PDF  file  contains  a  PDF  document  and  the 
resources  reference  by  that  document. 

Type  1  fonts 

Type  1  fonts,  described  in  detail  in  Adobe  Type  1  Font  Format,  by  Adobe 
Systems  Incorporated,  are  special-purpose  PostScript  language  programs  used 
for  defining  fonts.  They  use  a  specialized  subset  of  the  PostScript  language  for 
more  compact  representation  and  optimized  performance.  Compared  with  the 
larger  Type  3  fonts,  Type  1  fonts  can  be  defined  more  compactly  due  to  the  fact 
that  they  make  use  of  a  special  procedure  for  drawing  the  characters  that  results 
in  higher  quality  output  at  small  sizes  and  low  resolution.  They  also  have  a 
built-in  mechanism  for  specifying  hints,  which  are  data  that  indicate  basic 
features  of  the  character  shapes  not  directly  expressible  by  the  basic  PostScript 
language  operators. 

The  base  14  Type  1  fonts 

For  every  PDF  data  stream,  there  exists  a  core  set  of  fonts  that  are  guaranteed 
to  be  available  to  the  Acrobat  program.  These  fonts  are  the  PostScript  names  of 
14  Type  1  fonts,  known  as  the  “base  14  fonts”: 

►  Courier 

►  Courier-Bold 

►  Courier-BoldOblique 

►  Courier-Oblique 

►  Helvetica 
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►  Helvetica-Bold 

►  Helvetica-BoldOblique 

►  Helvetica-Oblique 

►  Times-Roman 

►  Times-Bold 

►  Times-ltalic 

►  Times-Boldltalic 

►  Symbol 

►  ZapfDingbats 

Because  the  only  external  resources  for  a  PDF  document  are  the  base  14  fonts, 
each  PDF  document  embeds  any  other  fonts  that  are  not  members  of  the  base 
14  fonts.  In  the  event  that  a  PDF  file  has  a  company  logo  or  image  on  a  set  of 
pages,  that  logo  or  image  is  also  embedded  within  the  document.  Barcode  fonts 
are  embedded  within  the  PDF  document  as  well. 


7.1.2  PDF  and  the  OnDemand  client 

If  you  plan  to  use  the  report  wizard  or  the  graphical  indexer  to  process  PDF  input 
files,  then  you  must  first  install  Adobe  Acrobat  or  Adobe  Acrobat  Approval  on  the 
PCs  from  which  you  plan  to  run  the  administrative  client.  You  must  purchase 
Adobe  Acrobat  and  Adobe  Acrobat  Approval  from  Adobe. 


Note:  Unless  the  end-user  PC  has  Acrobat  or  Acrobat  Approval  installed,  the 
end-user  OnDemand  client  does  not  perform  seamless  viewing  of  PDF 
documents.  We  recommend  that  you  purchase  Adobe  Acrobat  or  Adobe 
Acrobat  Approval  for  end  users  who  need  to  view  PDF  documents  from  the 
Windows  client. 


OnDemand  provides  the  ARSPDF32.API  file  to  enable  PDF  viewing  from  the  client. 
If  you  install  the  client  after  you  install  Adobe  Acrobat,  then  the  installation 
program  copies  the  API  file  to  the  Acrobat  plug-in  directory.  If  you  install  the  client 
before  you  install  Adobe  Acrobat,  then  you  must  copy  the  API  file  to  the  Acrobat 
plug-in  directory  manually.  Also,  if  you  upgrade  to  a  new  version  of  Acrobat,  then 
you  must  copy  the  API  file  to  the  new  Acrobat  plug-in  directory. 

The  default  location  of  the  API  file  is 
\Program  Fi 1 es\IBM\0nDemand32\PDF. 

The  default  Acrobat  plug-in  directory  is 

\Program  Fi 1 es\Adobe\Acrobat  x.y\Acrobat\Pl ug_ins, 

Here,  x.y  is  the  version  of  Acrobat,  for  example,  4.0,  5.0,  and  so  forth. 
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7.2  Indexing  issues  with  PDF 

When  indexing  PDF  data,  you  may  experience  surprising  results  related  to  the 
size  of  the  files  created  by  the  OnDemand  indexer  after  it  has  indexed  the  data. 
In  some  cases,  the  PDF  file  which  is  loaded  into  OnDemand  is  many  times  larger 
than  the  source  PDF  file. 

Here  is  an  example  of  why  the  initial  PDF  file  size  can  grow  to  be  multiple  times 
larger  than  the  original.  Suppose  that  OnDemand  receives  a  PDF  data  stream 
with  the  following  characteristics: 

►  A  100  page  PDF  file  which  includes  1  non-base  14  font. 

►  A  company  logo  on  every  5th  page. 

►  A  bar  code  font  on  every  5th  page  describing  the  customer  account  number. 

►  The  file  was  100k  bytes  in  size  and  OnDemand  was  required  to  index  that 
document  into  twenty  5-page  documents  representing  20  customer  accounts 
with  5  pages  of  customer  information  each. 

The  following  describes  how  the  output  PDF  file  would  be  generated  from  the 
original  PDF: 

►  Each  of  the  20  PDF  documents  would  include  any  and  all  fonts  that  are  not 
members  of  the  base  14  fonts.  OnDemand  would  have  20  copies  of  any 
non-base  14  font  in  the  resultant  indexed  PDF  file  (10  KB  of  font  would 
become  200  KB  worth  of  fonts) 

►  Each  of  the  20  PDF  documents  would  have  a  copy  of  the  company  logo 
instead  of  just  1  copy  of  the  company  logo  for  the  non-indexed  100  page 
document.  25KB  of  compressed  image  would  now  be  500KB  of  compressed 
image. 

►  Each  of  the  20  PDF  documents  would  have  a  copy  of  the  barcode  font 
required  to  print  the  customer  account  information  instead  of  just  1  copy  for 
the  non-indexed  1 00  page  document.  5KB  of  barcode  font  would  now  be 
100k  worth  of  bar  code  font. 

As  you  can  see,  the  original  100  pages  with  one  company  logo,  1  bar  code  font, 
and  1  non-base  14  font  will  have  become  20  wholly  contained  PDF  documents 
with  1  copy  of  the  non-base  14  font  each,  1  copy  of  the  barcode  font  each,  and  1 
copy  of  the  company  logo  each. 
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The  indexed  file  size  would  be  around  860k  bytes,  60k  bytes  being  the  actual  text 
in  the  100k  original  file,  and  40k  being  the  resources  in  the  original  file  which 
expanded  to  800k  bytes  through  duplication.  Considering  that  the  logo,  the  bar 
code  font  and  possibly  the  non-base  14  font  are  image,  you  can  see  how  the  file 
size  will  have  multiplied.  Due  to  the  extraction  of  the  fonts,  logos,  bar  code,  and 
pages  into  separate  documents,  the  result  is  that  extra  hardware,  disk,  and  RAM 
are  needed  in  order  to  accomplish  this  task.  A  discussion  of  what  this  means  in 
terms  of  performance,  as  well  as  an  illustration  of  this  process,  can  be  found  in 
Chapter  6,  “Performance”  on  page  131,  and  the  PDF  section  can  be  found  in 
section  6.3.1 ,  “PDF  data”  on  page  149 


7.2.1  Listing  fonts  in  a  PDF  file 

As  previously  discussed,  the  main  cause  of  PDF  file  size  increasing  after 
indexing  is  due  to  the  embedded  fonts  that  are  not  part  of  the  base  14  Type  1  font 
families.  If  you  are  experiencing  problems  with  PDF  file  sizes  growing  and  you 
suspect  that  it  is  the  number  of  custom  fonts  in  your  PDF  data,  then  there  is  a 
simple  way  within  the  Adobe  viewer  to  list  the  fonts  in  your  data.  Do  the  following 
steps: 

1 .  Display  your  PDF  document  in  the  Adobe  viewer. 

2.  Click  File  — >  Document  Properties  — >  Fonts... 

3.  You  should  see  a  list  of  fonts  for  the  document  such  as  the  one  shown  in 
Figure  7-1 


Figure  7- 1  Listing  fonts  in  PDF  document 

4.  If  the  PDF  file  you  used  is  very  large,  the  fonts  that  are  displayed  are  not  a 
complete  list  for  the  entire  report.  Click  List  All  Fonts...  in  order  to  obtain  a 
full  list. 
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Tip:  When  indexing,  OnDemand  uses  the  Adobe  parsing  technology  to 
produce  the  output  PDF  files.  If  you  are  experiencing  poor  performance  during 
indexing,  you  can  do  a  stand-alone  Adobe  parsing  test  by  clicking  List  All 
Fonts...  as  shown  in  Figure  7-1 .  If  this  operation  is  fast,  then  it  is  an 
OnDemand  problem;  if  it  is  slow,  then  the  performance  issue  is  caused  by  the 
PDF  data  stream. 


7.3  PDF  indexer 

The  PDF  indexer  can  process  an  input  file  that  contains  up  to  2.1  billion  pages, 
so  long  as  the  input  file  does  not  exceed  4  GB  in  size.  However,  the  amount  of 
data  that  can  be  processed  from  an  input  file  is  also  limited  by  the  amount  of 
memory  that  is  available  on  the  server  on  which  you  are  running  the  PDF 
indexer. 

Fonts 

The  PDF  indexer  must  be  able  to  access  fonts  to  insert  appropriate  information 
in  a  PDF  output  file.  If  a  font  is  referenced  in  an  input  file  but  is  not  available  on 
the  system,  the  PDF  indexer  substitutes  a  font,  usually  Courier. 

All  installations  should  verify  that  the  standard  Adobe  font  files  are  installed  in  the 
standard  font  directory.  For  installations  that  plan  to  use  the  PDF  indexer  to 
access  DBCS  fonts,  verify  the  locations  of  the  DBCS  font  files  and  export  or  add 
the  ACRO_RES_DIR  and  PSRESOURCEPATH  environment  variables. 

Graphical  indexer 

Since  Version  7.1  of  the  administrative  client,  it  has  been  possible  to  define  PDF 
reports  within  the  application  component  of  OnDemand  graphically  in  the  same 
way  as  line  data  and  AFP.  The  principle  of  indexing  PDF  data  is  the  same  as  all 
of  the  other  data  types  supported  by  OnDemand;  therefore,  triggers,  fields  and 
indexes  need  to  be  defined.  This  section  serves  as  an  introduction  to  the  PDF 
graphical  indexer  by  stepping  through  an  example  of  indexing  a  PDF  document. 

The  following  process  is  an  extract  from  Section  “PDF  Indexing”,  in  IBM  Content 
Manager  OnDemand  for  Multiplatforms  Release  Notes  for  Version  7.1.0.10.  The 
example  describes  how  to  use  the  graphical  indexer  from  the  report  wizard  to 
create  indexing  information  for  an  input  file.  The  indexing  information  consists  of 
a  trigger  that  uniquely  identifies  the  beginning  of  a  document  in  the  input  file  and 
the  fields  and  indexes  for  each  document.  Our  intention  here  is  to  elaborate  on 
this  example  by  clarifying  some  of  the  instructions,  and  throughout  each  step, 
adding  important  hints,  tips,  and  explanations. 
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The  process  is  as  follows: 

1 .  To  begin,  start  the  administrative  client. 

2.  Log  on  to  a  server. 

3.  Start  the  report  wizard  by  clicking  the  Report  Wizard  icon  on  the  toolbar.  The 
report  wizard  opens  the  Sample  Data  dialog  box. 

4.  Select  PDF  from  the  pull-down  list  of  data  types,  then  click  Select  Sample 
Data  to  open  the  Open  dialog  box. 

5.  Type  the  name  or  full  path  name  of  your  file  in  the  space  provided  or  use  the 
Browse  option  to  locate  your  PDF  file. 

6.  Click  Open.  The  graphical  indexer  opens  the  input  file  in  the  report  window. 

If  the  PDF  data  fails  to  view,  or  an  error  message  such  as  the  one  shown  in 
Figure  7-2  is  displayed,  then  make  sure  that  the  steps  in  7.1 .2,  “PDF  and  the 
OnDemand  client”  on  page  159  have  been  followed. 


Figure  7-2  Error  if  PDF  does  not  view 

7.  Press  the  FI  key  on  your  keyboard  to  open  the  main  help  topic  for  the  report 
window.  The  main  help  topic  contains  general  information  about  the  report 
window  and  contains  links  to  other  topics  that  describe  how  to  add  triggers, 
fields,  and  indexes.  Under  Options  and  Commands,  click  Indexer 
Information  page  to  open  the  Indexing  Commands  topic.  (You  can  also  use 
the  content  help  tool  to  display  information  about  the  icons  on  the  toolbar.) 
Under  Tasks,  Indexer  Information  page,  click  Adding  a  trigger  (PDF). 

8.  Close  any  open  help  topics  and  return  to  the  report  window. 

9.  Define  a  trigger  as  follows: 

a.  Find  a  text  string  that  uniquely  identifies  the  beginning  of  a  document.  For 
example,  Account  Number,  Invoice  Number,  Customer  Name. 

b.  Using  the  mouse,  draw  a  box  around  the  text  string.  Start  just  outside  of 
the  upper  left  corner  of  the  string.  Click  and  hold  mouse  button  one.  Drag 
the  mouse  towards  the  lower  right  corner  of  the  string.  As  you  drag  the 
mouse,  the  graphical  indexer  uses  a  dotted  line  to  draw  a  box.  When  you 
have  enclosed  the  text  string  completely  inside  of  a  box,  release  the 
mouse  button.  The  graphical  indexer  highlights  the  text  string  inside  of  a 
box. 
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Important:  We  recommend  that  the  box  that  you  create  around  the  text 
string  which  you  are  trying  to  collect  should  be  as  large  as  possible  in  order 
to  ensure  that  the  field  is  collected  at  load  time. 


Figure  7-3  shows  an  example  of  a  box  which  is  intended  to  capture  the 
text  string  Page  1.  You  can  see  that  the  box  is  much  larger  than  the  text 
string  and  also  it  overlaps  onto  text  which  we  do  not  wish  to  collect. 
However,  notice  the  Add  a  Trigger  box  which  was  displayed;  only  the 
string  Page  1  is  shown  in  the  Value  entry  field  which  means  that  only  the 
Page  1  text  was  fully  encapsulated  in  the  box.  Overlapping  other  text  may 
seem  like  an  unnecessary  precaution;  but  when  we  are  capturing  data 
with  the  PDF  graphical  indexer,  it  is  an  excellent  way  to  ensure  that  we 
have  encapsulated  all  of  the  text  string  that  we  need  to  capture. 


Quarterly  Financial  Report  for 
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Figure  7-3  Capturing  text  with  the  PDF  graphical  indexer 
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c.  Click  the  Define  a  Trigger  icon  on  the  toolbar  to  open  the  Add  a  Trigger 
dialog  box  shown  in  Figure  7-3.  Verify  the  attributes  of  the  trigger  by 
confirming  the  text  string  in  the  Value  field;  for  Triggerl ,  is  correct.  For 
trigger  1 ,  there  are  no  options  or  values  you  can  specify.  For  other 
triggers,  click  Help  for  assistance  with  the  other  options  and  values. 

d.  Click  OK  to  define  the  trigger. 

e.  To  verify  that  the  trigger  uniquely  identifies  the  beginning  of  a  document, 
first  put  the  report  window  in  display  mode.  Then  click  Select  tool  to  open 
the  Select  dialog  box.  Under  Triggers,  double-click  the  trigger:  The 
graphical  indexer  highlights  the  text  string  in  the  current  document. 
Double-  click  the  trigger  again:  The  graphical  indexer  should  highlight  the 
text  string  on  the  first  page  of  the  next  document.  Use  the  Select  dialog 
box  to  move  forward  to  the  first  page  of  each  document  and  return  to  the 
first  document  in  the  input  file. 

f.  Put  the  report  window  in  add  mode. 

10.  Define  a  field  and  an  index  as  follows: 

a.  Find  a  text  string  that  can  be  used  to  identify  the  location  of  the  field.  The 
text  string  should  contain  a  sample  index  value.  For  example,  if  you  want 
to  extract  account  number  values  from  the  input  file,  then  find  where  the 
account  number  is  printed  on  the  page. 

b.  Using  the  mouse,  draw  a  box  around  the  text  string.  Start  just  outside  of 
the  upper  left  corner  of  the  string.  Click  and  hold  mouse  button  one.  Drag 
the  mouse  towards  the  lower  right  corner  of  the  string.  As  you  drag  the 
mouse,  the  graphical  indexer  uses  a  dotted  line  to  draw  a  box.  When  you 
have  enclosed  the  text  string  completely  inside  of  a  box,  release  the 
mouse  button.  The  graphical  indexer  highlights  the  text  string  inside  of  a 
box. 


Important:  Use  exactly  the  same  principles  for  collecting  fields  as 
collecting  the  trigger  text  string  in  step  9  b  on  page  163.  If  the  fields  which 
need  to  be  collected  are  close  together,  we  recommend  overlapping  with 
adjacent  fields  in  order  to  ensure  that  the  box  is  as  large  as  possible  to 
ensure  that  the  data  is  collected  at  load  time. 


c.  Click  Define  a  Field  icon  on  the  toolbar  to  open  the  Add  a  Field  dialog 
box. 

d.  On  the  Field  Information  tab,  verify  the  attributes  of  the  index  field.  For 
example,  the  text  string  that  you  selected  in  the  report  window  should  be 
displayed  under  Reference  String;  the  trigger  should  identify  the  trigger  on 
which  the  field  is  based.  Click  Help  for  assistance  with  the  options  and 
values  that  you  can  specify. 
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e.  On  the  Database  Field  Attributes  tab,  verify  the  attributes  of  the  database 
field.  In  the  Database  Field  Name  field,  enter  the  name  of  the  application 
group  field  into  which  you  want  OnDemand  to  store  the  index  value.  In  the 
Folder  Field  Name  field,  enter  the  name  of  the  folder  field  to  appear  on  the 
client  search  screen.  Click  Help  for  assistance  with  the  other  options  and 
values  that  you  can  specify. 

f.  Click  OK  to  define  the  field  and  index. 

g.  To  verify  the  locations  of  the  fields: 

i.  Put  the  report  window  in  display  mode.  The  fields  should  have  a  blue 
box  drawn  around  them. 

ii.  Next,  click  Select  tool  to  open  the  Select  dialog  box. 

iii.  Under  Fields,  double-click  Field  1.  The  graphical  indexer  highlights 
the  text  string  in  the  current  document.  Double-click  Field  1  again.  The 
graphical  indexer  should  move  to  the  next  document  and  highlight  the 
text  string.  Use  the  Select  dialog  box  to  move  forward  to  each 
document  and  display  the  field.  Then  return  to  the  first  document  in  the 
input  file. 

h.  Put  the  report  window  in  add  mode. 

1 1  .Click  Create  Indexer  Parameters  and  Fields  Report  to  create  the  indexer 
parameter  report  that  the  PDF  indexer  uses  to  process  the  input  files  that  you 
load  into  the  application.  At  a  minimum,  you  need  one  trigger,  one  field,  and 
one  index.  Refer  to  OnDemand  Indexing  References  for  details  about  the 
indexing  parameters. 

12.  When  you  have  finished  defining  all  of  the  triggers,  fields,  and  indexes,  close 
the  report  window  by  pressing  Esc  on  your  keyboard. 

13.  Click  Yes  to  save  the  changes  to  the  indexer  parameters. 

14. On  the  Sample  Data  window,  click  Next  to  continue  with  the  report  wizard. 


7.3.1  PDF  indexing  on  z/OS 

Indexing  PDF  documents  on  z/OS  uses  the  same  procedure  described  in  the 
preceding  section.  Flowever,  the  load  process  needs  modification  of  the  ARSLOAD 
procedure.  You  have  to  specify  the  following: 

►  The  Adobe  font  mapping  table  (has  to  be  created) 

►  A  font  data  set  that  is  created  by  the  PDF  indexer  at  runtime  to  hold  the 
names  of  the  fonts  that  are  located  in  the  font  path  in  the  runtime  directory 

►  A  data  set  that  contains  the  attributes  of  the  temporary  working  space  for  the 
PDF  libraries 
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Creation  of  the  font  mapping  table 

The  font  mapping  table  is  a  z/OS  data  set  where  every  Adobe  Type  1  font  is 
referenced  in  the  system.  This  mapping  table  is  not  shipped  with  the  base 
OnDemand  code.  Adobe  fonts  are  not  owned  by  IBM.  You  have  to  buy  the  fonts 
from  Adobe  and  upload  them  in  a  binary  format  to  your  z/OS  system.  The  PDF 
indexer  needs  access  to  the  fonts  to  be  able  to  insert  the  appropriate  information 
into  the  PDF  output  file.  If  a  font  is  referenced  but  not  available  on  the  system,  it 
is  substituted  with  a  standard  font. 

The  sample  delivered  in  the  documentation  consists  of  standard  Type  1  Adobe 
fonts.  You  can  create  a  sequential  file  or  use  a  Partition  Data  Set  (PDS)  to 
generate  the  font  mapping  table.  The  example  created  here  is  a  Partition  Data 
Set  where  every  member  contains  one  font.  Table  7-1  shows  the  Data  Control 
Block  (DCB)  parameters  for  the  allocation  of  the  font  mapping  table.  Figure  7-4 
shows  the  sample  PDS  member  list. 


Table  7- 1  Space  allocation  for  font  mapping  table 


Space 

LRECL 

RECFM 

BLKSIZE 

DSORG 

Cyl  1,1 

255 

VB 

27998 

PO 

Figure  7-4  Sample  PDF  font  mapping  table  as  PDS 
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Example  7-1  shows  what  the  ARIAL  font  looks  like  in  the  PDS  member  after 
uploading  this  font  to  the  z/OS  system.  All  fonts  are  ASCII  character  set. 

Example  7- 1  Arial  font  member  on  z/OS 

% IJPS-A dobeFon t- 1 . 0:  AriaIMT  001 .001  .%%CreationDate:  Wed  Jan  27  13:02:03 
1999: %%V 


Modification  of  the  ARSLOAD  procedure  for  PDF  indexing 
The  arsload  procedure  has  to  be  modified  to  archive  PDF  data.  The  procedure 
to  create  an  application  group  is  the  same  as  described  earlier  in  the  multi 
platforms  section.  The  following  JCL  statements  (Example  7-2)  have  to  be  added 
to  the  arsload  procedure  or  uncommented  if  it  already  exits. 

Example  7-2  JCL  statements  to  be  added  for  PDF  Indexer 

ADOBERES  DD  DSN=TEAM5. PDFLIB . RESOURCE . INDEX (ADOBE RES) ,DISP=SHR 
ADOBEFNT  DD  DSN=TEAM5. PDF405 . PLUS PIC. ADOBE FNT. LST,DISP=SHR 
TEMPATTR  DD  DSN=TEAM5. PDF405 . PLUSP1C. TEMPATTR, DISP=SHR 


ADOBERES  DD  is  used  by  the  OnDemand  PDF  indexer.  It  specifies  the 
member  that  points  to  the  location  of  the  ADOBE  font  mapping  table  (the  PDS 
data  set  that  is  previously  created).  Example  7-3  shows  the  ADOBERES 
member. 


Example  7-3  ADOBERES  member 

ickick'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'kick'k'k'k'k'k 

TEAM5. PDFLIB. RESOURCE. I ND EX (T 1 P FA  14) 

ick'kic'k'kickicic'kicic'kick'kick'kick'kickic'k'kickicickicic'k 


Member  T1 PFA1 4  contains  the  statements  as  shown  in  Example  7-4.  It  can  point 
to  any  data  set  containing  the  ADOBE  fonts. 

Example  7-4  Location  of  ADOBE  font  mapping  table 

PS-Resources-1.0 
FontOutl i ne 


FontOutl i re 

Ari at MT=TEAM5. PDFLIB. RESOURCE. T1PFA (ARIAL) 

Arial -BoldMT=TEAM5. PDFLIB. RESOURCE. TIPFA(ARIALB) 

Ari  al-BoldItalicMT=TEAM5. PDFLIB. RESOURCE. TIPFA(ARIALBI) 
Arial -Ital icMT=TEAM5. PDFLIB. RESOURCE. T1PFA (ARI ALI ) 
Ccmrier=TEAM5.  PDFLIB.  RESOURCE.  TIPFA(COUR) 
Ccmrier-Bold=TEAM5.  PDFLIB.  RESOURCE.  TIPFA(COURB) 
Courier-BoldObl  ique=TEAM5. PDFLIB. RESOURCE. TIPFA(COURBI) 
Courier-Obi ique=TEAM5. PDFLIB. RESOURCE. TIPFA(COURI) 
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Symbol =TEAM5 . PDFLI B . RESOURCE . T1 P FA (SYMBOL) 

TimesNewRomanPS-Bol dMT=TEAM5. PDFLIB. RESOURCE. TIPFA(TIMENRB) 
TimesNewRomanPS-Boldltal i cMT=TEAM5. PDFLIB. RESOURCE. TIP  FA (TIMENRBI) 
TimesNewRomanPS-Ital i cMT=TEAM5. PDFLIB. RESOURCE. TIP  FA (TIMENRI) 
TimesNewRomanPSMT=TEAM5. PDFLIB. RESOURCE. TIPFA(TIMENR) 
ZapfDingbats=TEAM5. PDFLIB. RESOURCE. TIPFA(ZAPFDING) 


The  following  Data  Control  Block  (DCB)  (Table  7-2)  is  used  for  this  library. 
Table  7-2  Data  Control  Block  used  for  ADOBERES  data  set 


Space 

LRECL 

RECFM 

BLKSIZE 

DSORG 

Cyl  1,1 

80 

FB 

8800 

PDS 

ADOBEFNT  DD  is  used  by  the  OnDemand  PDF  indexer.  It  specifies  the  data  set 
which  is  used  by  the  OnDemand  PDF  indexer  at  run  time  to  hold  the  names  of 
the  fonts  that  are  located  in  the  font  path  and  in  the  runtime  directory. 


Important:  This  file  normally  does  not  exist  when  the  PDF  indexer  is  not  used 
before.  The  indexer  does  not  create  it  and  if  you  run  the  arsload  procedure 
with  a  non-catalog  data  set,  it  fails  with  a  JCL  error.  You  have  to  create  this 
data  set  prior  running  the  arsload  procedure.  You  can  not  just  allocate  an 
empty  data  set  because  the  indexer  is  looking  at  the  end  of  the  data  set  and 
searches  for  the  ASCII  End  of  FILE  tag  which  is  X’OA’.  Edit  the  allocated  data 
set  in  Flex  and  put  X’OA’  at  the  end  on  the  file. 


The  following  DCB  (Table  7-3)  was  used  for  ADOBEFNT  data  set. 
Table  7-3  Data  Control  Block  used  for  ADOBEFNT  data  set 


Space 

LRECL 

RECFM 

BLKSIZE 

DSORG 

Cyl  2,2 

256 

VB 

27998 

PS 

TEMPATTR  DD  is  used  by  the  OnDemand  PDF  indexer.  It  specifies  the  data  set 
that  contains  the  attributes  of  the  temporary  working  space  for  the  PDF  libraries. 
The  content  of  the  data  set  is  as  shown  in  Example  7-5. 

Example  7-5  Content  of  TEMPATTR  data  set 

mrit=vio,cyl , spaceround,primary=5,secondary=5,recfm=f ,1  reel =13030, bl ksize=13030 
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INPUT  DD  points  to  the  PDF  document  which  has  to  be  uploaded  to  the  z/OS 
system.  It  can  be  uploaded  as  an  HFS  file  or  as  a  z/OS  data  set.  If  you  want  to 
use  it  as  a  z/OS  data  set,  the  following  DCB  (Table  7-4)  must  be  used. 

Table  7-4  Data  Control  Block  used  for  INPUT  data  set 


Space 

LRECL 

RECFM 

BLKSIZE 

DSORG 

Cyl  5,5 

80 

FB 

27920 

PS 

If  the  PDF  data  set  is  not  transferred  correctly  to  the  z/OS  system,  you  may  see 

ABENDS  and  DUMPS  when  trying  to  index  it. 

Limitations 

There  are  some  system  limitations  which  have  to  be  considered  when  using  the 

OnDemand  PDF  indexer: 

►  The  PDF  indexer  cannot  process  data  sets  that  are  greater  than  4  GB  in  size. 

►  The  PDF  indexer  supports  DBCS  languages.  Since  IBM  does  not  provide  any 
DBCS  fonts,  you  have  to  purchase  them  from  ADOBE. 

►  Input  data  delimited  with  Postscript  Pass  through  markers  cannot  be  indexed. 

►  The  Adobe  Toolkit  does  not  validate  link,  destinations,  or  bookmarks  to  other 
pages  in  a  document  or  to  other  documents.  Links  or  bookmarks  may  or  may 
not  resolve  correctly,  depending  on  how  you  segment  your  documents. 

►  Postscript  data  generated  by  applications  must  be  processed  by  a  conversion 
program  such  as  Acrobat  Distiller  before  you  run  the  PDF  indexer.  Acrobat 
Distiller,  however,  is  not  available  in  a  z/OS  environment. 
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Installing  and  customizing 
ODWEK 


In  this  chapter,  we  introduce  the  three  common  server  access  points  to  an 
OnDemand  server  via  the  OnDemand  Web  Enablement  Kit  (ODWEK).  We 
discuss  how  these  access  points  can  be  used.  With  sample  code  and  working 
examples,  we  demonstrate  how  integration  code  could  be  written  in  order  to 
customize  the  access  to  data  stored  in  OnDemand. 

The  following  topics  are  covered: 

►  Introducing  the  Common  Server  access  points 

►  Using  the  Java  API 

►  Deploying  the  ODWEK  servlet 


©  Copyright  IBM  Corp.  2003.  All  rights  reserved. 
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8.1  ODWEK  architecture 


The  OnDemand  Web  Enablement  Kit  (ODWEK)  was  designed  as  a  tool  kit  for 
Web  developers  to  create  browser  based  interfaces  to  an  OnDemand  server. 
Version  7.1  of  ODWEK,  with  the  latest  level  of  maintenance  applied,  supports 
access  to  OnDemand  servers  on  all  supported  server  platforms  (UNIX,  Microsoft 
Windows  NT,  iSeries,  and  zSeries). 

When  the  ODWEK  code  is  installed,  there  are  three  options  available  for  the 
method  of  communication  back  to  the  OnDemand  server.  The  sections  below 
provide  more  detailed  information  about  each  of  these  three  access  methods, 
and  they  should  be  used  in  conjunction  with  the  following  two  references: 

►  IBM  Content  Manager  OnDemand  -  Web  Enablement  Kit  Installation  and 
Configuration  Guide,  SC27-1000  ( ODWEK  Installation  and  Configuration 
Guide) 

►  IBM  Content  Manager  OnDemand  for  Multiplatforms  Release  Notes  for 
Version  7.1.0.10 


8.1 .1  ODWEK  access  to  OnDemand 

Using  ODWEK,  there  are  three  different  access  points  to  an  OnDemand  Server: 

►  CGI:  Through  the  arswww.cgi  executable 

►  Servlet:  Through  the  ArsWWWServlet  interface 

►  Java  API:  By  writing  your  own  Java  program  similar  to  the  ArsWWWServlet 
but  containing  custom  functions  based  on  a  set  of  requirements 

CGI 

The  CGI  implementation  of  ODWEK  is  probably  the  most  simple  one  of  the  three 
access  points  to  configure.  Refer  to  Section  “Deploying  the  CGI  program”,  in 
Chapter  2,  “Installation  and  Configuration”,  in  the  ODWEK  Installation  and 
Configuration  Guide  for  details  on  the  files  that  must  be  placed  within  the  HTTP 
Web  server  environment.  For  CGI  access  to  OnDemand,  a  Web  server  is 
required  in  order  to  execute  the  CGI  program;  but  an  application  server  is  not 
required.  An  instance  of  the  arswww.cgi  program  is  launched  every  time  a  user 
performs  an  operation  which  requires  connection  to  the  OnDemand  server  (such 
as  search  and  retrieval).  Issues  associated  with  this  are  discussed  in  Chapter  6, 
“Performance”  on  page  131. 

Servlet 

If  a  Java  servlet  implementation  of  ODWEK  is  chosen,  an  HTTP  Web  server  and 
a  Java  enabled  application  server  are  required.  Refer  to  “Deploying  the  servlet”  in 
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Chapter  2,  “Installation  and  Configuration”,  in  the  ODWEK  Installation  and 
Configuration  Guide  for  guidelines  on  the  process  that  must  be  followed  in  order 
to  configure  and  deploy  the  ODWEK  servlet. 


Important:  The  method  of  deploying  a  servlet  varies  greatly  between  different 
vendors  and  even  different  versions  of  application  servers.  Guidance  specific 
to  the  IBM  WebSphere  application  server  is  given  later  in  this  redbook  under 
“Deploying  the  ODWEK  servlet”  on  page  189. 


The  fundamental  difference  between  the  servlet  and  the  CGI  implementation  of 
ODWEK  is  that  the  servlet  is  managed  by  an  application  server  while  the  CGI  is 
executed  by  an  HTTP  Web  server.  This  means  that  rather  than  executing  many 
instances  of  the  code  and  therefore  allocating  memory  for  these  multiple  threads, 
as  in  the  case  of  CGI,  the  servlet  runs  as  a  single  instance  and  memory  is 
managed  by  the  application  server.  Issues  associated  with  this  are  discussed  in 
Chapter  6,  “Performance”  on  page  131. 

Java  API 

The  servlet  that  is  supplied  with  ODWEK  after  a  standard  installation  of  the 
product  is  a  working  example  of  a  servlet  that  has  been  written  using  the  Java 
APIs  in  order  to  access  OnDemand.  When  using  these  APIs  with  ODWEK,  an 
application  server  and  an  HTTP  Web  server  are  required  if  clients  require  access 
to  OnDemand  via  a  browser.  However,  unless  you  are  using  the  Java  APIs  to 
write  a  Web  application,  neither  a  Web  Server  nor  an  Application  Server  are 
required.  For  example,  if  a  program  is  written  using  these  Java  APIs  for  bulk 
retrieval  of  documents  from  OnDemand,  you  may  want  to  output  the  objects  to  a 
file  system  without  using  a  Web  server  or  an  application  server. 

8.2  Integrating  with  APIs 

In  the  previous  sections,  we  have  seen  that  there  are  3  access  points  to  an 
OnDemand  server  using  the  APIs  supplied  with  ODWEK.  Two  of  these  access 
points  (CGI  and  ArsWWWServlet)  are  provided  with  the  standard  install  code  of 
ODWEK  as  implementation  options  and  the  third  access  point  requires  custom 
coding  using  the  Java  APIs. 

Assuming  that  you  use  a  browser  to  view  information  from  OnDemand,  there  are 
two  places  that  custom  code  need  to  be  written  in  order  to  integrate  with  the 
ODWEK  APIs.  The  first  place  is  the  HTML  Web  pages,  which  present  the  user 
interface,  such  as  logon,  search,  and  hit-list  screens;  the  second  place  is  for  a 
custom  servlet  that  is  application  specific.  Figure  8-1  illustrates  the  various 
components  within  ODWEK  that  make  up  the  three  access  points  into  an 
OnDemand  server  and  also  shows  the  software  that  is  required  for  each. 
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Client  Browser  Access 


Figure  8-1  ODWEK  with  CGI,  ArsWWWServlet,  and  a  custom  servlet 


The  three  HTML  documents  represent  the  three  access  points  into  the 
OnDemand  server.  Figure  8-1  illustrates  all  three  methods  of  linking  to  an 
OnDemand  server.  In  practice,  an  implementation  of  ODWEK  would  only  have 
one  of  these  access  methods  configured  for  operation. 


8.2.1  HTML  samples  (URL  API) 

Samples  of  the  HTML  shown  in  Figure  8-1  are  provided  in  the  samples  directory 
after  the  standard  installation  of  the  ODWEK  product.  Regardless  of  the  access 
point  (CGI,  servlet  or  Java  API)  used  to  connect  to  OnDemand,  if  the  user 
requires  to  view  the  data  from  a  browser,  then  a  Web  page  is  required.  You  must 
either  customize  the  HTML  samples  that  are  provided  or  simulate  the  function  of 
these  samples  via  Java  script,  or  as  part  of  a  JSP  or  any  standard  Web 
presentation  language. 
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The  HTML  samples  provide  the  basic  functions  to  search  and  retrieve 
documents  from  OnDemand;  but  they  do  not  show  samples  of  all  of  the  possible 
APIs  that  are  available  for  use.  The  HTML  in  Example  8-1  is  a  working  example 
of  the  URL  APIs  being  used  within  an  HTML  document.  The  HTML  is  a  lengthy 
example;  but  it  demonstrates  a  number  of  uses  for  the  URL  APIs.  More 
importantly,  it  is  a  real  customer  example  from  the  intranet  of  a  company  in  the 
UK. 


|  5e&E  Documents  Microsoft  Internet  Explorer 

File  Edit  View  Favorites  Tools  Help 

J  ^  ^Search  _*]  Favorites  Media  j)  l^j*  _t  si  ■  j| 

|  Address  F:\$user\Martin\OnDemand\ODWEK\sample  html  API\ondemandhome.htm 

v|  {V>G0 

IN  farm 


E&E  Archive  is  simply  an  Electronic  Filing  Cabinet  which  will  allow  you  to  search  for  and  retrieve  a  growing  number  of 
document  types.  First-time  users  click  here  as  you  will  need  to  install  viewing  software. 


Purchase  Invoices 

bv  BaaN  reference 
by  value 
bv  supplier 


MSDS  -  Material  Safety  Data  Sheets 

by  reference,  product  code  or  description 


Or  type  the  required  MSDS  Reference:  ar,d  c*'c*c 

KUlilU  or  press  return. 

Administration  ■  to  Archive  new  MSDS  •  restricted  access 


Certificates  Of  Analysis 

For  Coventry  &  Fiske  initially 

Administration  •  to  Archive  CofA  •  restricted  access 
Stats  Group  Search 


H 

1  H 

^  My  Computer 

Figure  8-2  Screen  display  of  a  fully  integrated  ODWEK  installation 


The  code  sample  shown  in  Example  8-1  has  been  altered  to  remove  the  server 
names,  IP  addresses,  and  various  other  sensitive  data  such  as  user  IDs  and 
password. 
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Example  8-1  Sample  of  the  URL  APIs  used  In  HTML 

<! DOCTYPE  HTML  PUBLIC  "-//W3C//DTD  HTML  4.0  Transi ti onal //EN"> 

<HTML  ><HEAD><TITLE>E&E  Document s</TITLE> 

<META  content="text/html ;  charset=wi ndows-1252"  http-equi v=Content-Type> 

<L I NK  href=l1  ./Home_fi  1  es/f  i  1  el  i  st  .xml "  rel  =Fi  1  e-Li  st> 

<META  content="MSHTML  5.00.3103.1000"  name=GENERATOR> 

</HEAD> 

<B0DY  aLink=#009966  bgCol or=003399  1 ang=EN-GB 

link=#009966  styl e="tab-i nterval :  36. Opt"  vLink=#009966  onLoad=""> 

<d i v  id="Layerl"  style="position:absolute;  left:381px;  top:278px;  width:415px;  height: 1 17px ; 
z-index:l"><img  src="inform_gold2.gif"  al t= " El  1 i s  &  Everard  Archive"  width="396" 
height="115"></div> 

<d i v  id="Layer2"  style="position:absolute;  1  eft : 33 1 px ;  top:7px;  width:128px;  height:29px; 
z-index:2"><img  src="archive.gif"  width="120"  height="32" > 

</di v> 

<div  id="Layer3"  style="position:absolute;  1  eft :  130px ;  top:88px;  width:241px;  height :  180px ; 
z-index:3"><img  src="fil ing.gi f"  width="270"  height="223"  al t= "Ellis  &amp;  Everard 
Archive" ></div> 

<div  id="Layer4"  style="position:absolute;  1  eft : 404px ;  top:122px;  width:371px;  hei ght: 134px; 
z-index:4"> 

<pxfont  si  ze="2"  face="Gill  Sans"  col  or="#FFFFFF">  </font> 

<font  si ze=4>  <font  size="2"  face="Gill  Sans"  col or="#FFFFFF"><b>MSDS  -  Material 
Safety  Data  Sheets<bxbr> 

<a  href="sds3.htm"><b>by  reference,  product  code  or  description</bx/a></b></bx/font><font 
si ze=4><b><b> 

<form  action=http://nn.nn.nn.nn/cgi-bin/arswww.cgi  method=post> 

<font  face="Gi 1 1  Sans"  col or="#FFFFFF"  size="2"> 

<input  name=_folder  type=hidden  value=msds> 

<input  name=_di spl ay_fiel ds  type=hidden  value="MSDS  reference, Product, Date  Revised, Date 
Added, Revision"> 

<input  name=_function  type=hidden  value=dochitl ist> 

<input  name=_max_hits  type=hidden  value=50> 

<input  name=_password  type=hidden  val ue=XXXXXXX> 

<input  name=_server  type=hidden  value=nn.nn.nn.nn> 

<input  name=_user  type=hidden  val ue=XXXXXXX> 

<input  name=_html  type=hidden  value=template.htm> 

</font><font  size="2"  face="Gill  Sans"  col or="#FFFFFF">Or  type  the  required 
MSDS  Reference: 

<input  name="MSDS  reference"  size=6  val ue="A001"> 
and  click 

<input  type=submit  value=Submit  name="submi t"> 
or  press  return .</font> 

</form> 

</b> 

<pxf0nt  face="Gi  1 1  Sans"  color="#FFFFFF"  size="2"xbxa 
href =" http://nn.nn.nn.nn/0nDemand.nsf/MSDSRequest70penForm"> 

Administration  -  to  Archive  new  MSDS  -  restricted  access</a></b>  </font></p> 
</b></font></font></di v> 
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<div  id="Layer5"  style="position:absolute;  left:7px;  top:259px;  width:349px;  hei ght : 113px; 
z-index:5"> 

<p>&nbsp; 

<font  size=4><font  size=4><font  size=4> 

<p><font  size="4"  face="Arial,  Helvetica,  sans-seri  f  "><font  size=“2"  col  or=“#FFFFFF''><b><font 
face="Gi 1 1  Sans"><strong>Certi fi cates 
Of  Analysi s<b><br> 

<a 

href =" http://nr.rr.rr.rr/cgi -bir/arswww.cgi ?_function=searchcrit&_user=XXXXXXX&_password=XXXXXX 
X&_server=nn.nn.nn.nn&_html=template.htm&_folder=CofaScanNetwork"xb>For 

Coventry  &  Fiske  initial ly</b></a>  </b></strong></font></b></font></font><strong><font 
face="Gi 1 1  Sans"  col or="#FFFFFF"  si ze="2"><b><a 
href =" http ://rr.rn.rr.rr/ondemand.rsf/searchform2?0penform"><br> 

Administration  -  to  Archive  CofA  -  restricted  access</a><a 
href ="  http://nn.nn.nn.nn/OnDemand.nsf /Search  Form?OpenForm"xbr> 

Stats  Group  Search</a></b></font></strong></p> 

</font></font></f ort></di v> 

<d i v  id="Layer6"  style="position:absolute;  left:9px;  top:131px;  width:130px;  height:95px; 
z-index:6"><font  face="Gill  Sans"  col or="#FFFFFF"  size="2"> 

</font> 

<px/p> 

<pxbr> 

<font  size="2"  f ace=  "Gil  1  Sans"  col or="#FFFFFF"xb>Purchase  Irvoi ces<font 
col  or="  #006699  "xb><br> 

<a 

href="//nn.nn.nn.nn/cgi-bin/arswww.cgi?_function=searchcrit&_server=nn.nn.nn.nn&_folder=Purchas 
el nvoi ces&_user=XXXXXXX&_password=ondemand2&_html =templ ate . htm"><b>by 
BaaN  refererce</b></a>  </bxbr> 

<a 

href ='7/nn.nn.nn.nn/cgi-bin/arswww.cgi?_function=searchcrit&_server=nn.nn.nn.nn&_folder= Puri nvv 
al &_user=XXXXXXX&_password=ondemand2&_html =templ ate . htm"><b>by 
value  </b></a>  </font></b><font  col  or="#006699"xbr> 

<a 

href="//nn.nn.nn.nn/cgi-bin/arswww.cgi?_function=searchcrit&_server=nn.nn.nn.nn&_folder=Purinvs 
uppl ier&_user=XXXXXXX&_password=ondemand2&_html  =templ  ate.  htm"><b>by 
supplier  </b></a>  </font></font> 

</di v> 

<div  id="Layer7"  style="position:absolute;  left:6px;  top:14px;  width:93px;  hei ght : 62px ; 
z-index:7"><a  href="http://rr.rr.rr.rr/home.html"><img  src="inform2.gif"  width="85"  height="29" 
border="0"></a></di v> 

<d i v  id="Layer8"  style="position:absolute;  left:124px;  top:53px;  width:651px;  height: 20px; 
z-index:8"><font  face="Gill  Sans"  col or="#FFFFFF"  size="2">E&amp;E 
Archive  is  simply  an  Electronic  Filing  Cabinet  which  will  allow  you  to  search 
for  and  retrieve  a  growing  number  of  document  types.  <b><a  href="ondemandhel  p.htm">Fi rst-time 
users  click  here</a></b>  as  you  will  need  to  install  viewing  softwares!  [if 
! support  Empty Paras] > 

</fontx/di  v> 

<D I V  al  i gn=center><B>  <font  col or=''#FFFFFF"  size="5"  f ace= "Gill  Sans">  </font> 

</B>  <B>  </B>  <B> 
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<p></p> 

<font  f ace= "Gil  1  Sans"  col or="#FFFFFF"  si ze="2"><! [i f  ! supportEmptyParas] ></font></B> 

<D I V  align=left> 

<P><font  face="Gi 1 1  Sans"  col or="#FFFFFF"  si ze="2"><br> 

<br> 

</font></P> 

<P><font  si ze="2"  face="Gill  Sans"  col or="#FFFFFF"><br> 

<BR> 

</font> 

<F0NT  size=4><F0NT  size=4><F0NT  size=4><F0NT  size=4> 

<P><font  si ze="2"  face="Gill  Sans"  col or="#FFFFFF"><B><br> 

</b></font></P> 

<font  face="Gi 1 1  Sans"  col or="#FFFFFF"  size="2"> 

<SCRIPT  LANGUAGE=" JavaScri pt"> 

<!-- 

document. forms[0]  .elements[8]  .focus() ; 
document .forms [0] .elements [8] . sel ect () ; 

//  -> 

</SCRIPT> 

</font><font  f ace= "Gi 1 1  Sans"  col or="#FFFFFF">  </font>  </font></font></font></font></DIV> 
</DIV></ BOD Y></ HTM  L> 


To  fully  complete  this  code  sample,  we  included  the  source  of  the  sds3 .  htm  file  in 
Example  8-2  that  is  referenced  by  the  HTML  sample  in  Example  8-1 . 


Example  8-2 

<HTML> 

<HEAD> 

<META  HTTP-EQUIV= "Content -Type"  CONTENT="text/html ;  charset=wi ndows-1252"> 

<META  NAME="Generator"  CONTENT="Notepad"> 

<TITLE>EEpl c  -  Product  SDSs</TITLE> 

</HEAD> 

<FRAMESET  col s="180,572*"  rows="*"  border="0"  framespacing="0"  frameborder="NO"> 

<FRAME  src=" http://nn.nn.nn.nn/openaccessdbs/sdsnew.nsf/SearchForm70pen Form"  name="si denav" 
scroll i ng="N0"  noresize  margi nwi dth="5"  marginheight="10"  frameborder="NO"> 

<FRAME  name="main2"  marginwidth="0"  scroll ing="AUT0"  marginheight="0"  frameborder="NO" 
src="http://nn.nn.nn.nn/openaccessdbs/sdsnew.nsf/ProductCodes?openview&amp;count=15"> 
</FRAMESET> 

<N0FRAMES> 

<B0DY  TEXT="#ffffff "  LINK="#f f ff f f "  VLINK="#ffffOO"  BGC0L0R="#ff f f ff "  al i n k= " #66 FF33 "> 

</B0DY> 

</N0FRAMES> 

</HTML> 


Refer  to  Chapter  5,  “API  Reference”,  in  ODWEK  Installation  and  Configuration 
Guide  for  a  full  reference  of  how  to  use  the  URL  APIs. 
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8.2.2  Java  API  samples 

After  a  standard  installation  of  ODWEK,  there  is  documentation  on  the  Java  APIs 
in  the  form  of  a  ZIP  archive  located  in  the  API  directory.  The  HTML  files  contained 
within  the  ZIP  file  explain  usage  of  the  APIs.  In  this  section,  we  show  how  the 
APIs  can  be  used,  by  presenting  working  examples  of  Java  code  that  contain 
ODWEK  Java  API  calls.  We  do  not  show  examples  of  all  of  the  APIs  available; 
but  based  on  the  examples  that  we  have  here,  it  should  be  possible  to  get  an 
understanding  of  the  principles  behind  using  them. 

In  order  to  compile  and  run  these  samples,  some  preliminary  work  must  be  done: 

►  The  Java  Development  Kit  should  be  installed  as  a  prerequisite. 

►  Ensure  that  the  ODWEK  shared  library  (ARSWWWSL.dl  1  on  UNIX  and 
Windows)  is  accessible: 

-  Windows:  The  ODWEK  install  directory  must  be  in  the  System  path. 

-  UNIX:  The  user  running  the  Java  program  should  have  the  ODWEK  install 
directory  as  part  of  the  PATH  variable. 

-  OS/390:  In  UNIX  System  Services,  the  user  running  the  Java  program 
should  have  the  ODWEK  install  directory  as  part  of  the  PATH  variable. 

►  Ensure  that  the  directory  containing  the  file  ODAPI .  jar  is  in  the  CLASSPATH. 

►  The  Java  API  does  use  the  arswww.  i  ni  file,  although  it  does  not  require  a 
Web  server  running.  Ensure  that  all  referenced  paths  in  the  arswww.ini  file 
actually  exist. 

Logon  and  search 

The  code  sample  in  Example  8-3  is  a  working  example  of  a  logon  to  an 
OnDemand  server,  the  opening  of  a  folder  called  Credit  Card  Statements,  and 
then  search  on  this  folder  followed  by  a  logoff.  Also,  inside  this  code  sample, 
actions  such  as  opening  the  folder  and  generating  the  hit  list  are  timed  in  order  to 
assess  performance  and  for  debugging  purposes. 

Example  8-3  Code  sample  of  logon  and  search 

import  java.uti 1 
import  java.io.*; 
import  com.ibm.edms.od.*; 

publ ic  class  Search 
{ 

public  static  void  main  (String  argv[]) 

{ 

int  rc; 

int  numFolders; 
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byte []  data; 

String[]  displayList; 

Fi  1 eOutputStream  file; 

ODServer  odServer; 

ODFolder  odFolder; 

ODCriteria  odCrit; 

Vector  hits; 

ODHit  odHit; 

Vector  rotes; 

Date  before,  after; 

Date  program_start,  program_end; 


if  (argv. length  <  4) 

{ 

System. out. println("usage:  java  Search  <server>  <user>  <pw>  <config 
dir>  [<1  ocal  server  dir>]“); 
return ; 

} 


try 

{ 

program_start  =  new  Date(); 
odServer  =  new  ODServer  (); 

odServer. initialize(argv[3] , 

"Search. java") ; 


before  =  new  Date() ; 
if  (argv. length  ==  4) 

odServer. logon(argv[0] , 
argv[l] , 
argv[2]) ; 

else  if  (argv. length  ==  5) 
odServer. logon(argv[0] , 
argv[l] , 
argv[2] , 

ODConstant.CONNECT_TYPE_LOCAL, 

0, 

argv  [4] ) ; 

after  =  new  Date() ; 

System. out. pri ntl n ("1 ogon :  "  +  (after. getTime()  - 
before. getTime())) ; 

before  =  new  Date() ; 

if(  odServer. getNumFolders()  >  0  ) 

{ 

Enumeration  g  =  odServer. getFol derNames () ; 
do 
{ 
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System. out. println(" fol der:  "+(String)g.nextElement()) ; 

} 

while(g.hasMoreElementsO) ; 

} 

odFolder  =  odServer.openFol der("Credit  Card  Statements"); 
after  =  new  Date() ; 

odCrit  =  odFol  der.getCri teri a("Date") ; 
before  =  new  Date() ; 
hits  =  odFolder. search() ; 
after  =  new  Date() ; 

//System. out. println("  Number  of  hits:  "  +  hits.sizeO); 

/ / d i s  p 1  ay  List  =  odFol der. getDi splayOrder() ; 

//for(  int  i  =0;  i  <  displayList. length;  i++) 

//{ 

//System. out. println("MAS  "+  d i s p 1  ay List[i] ) ; 

//} 

//if  (hits.sizeO  >  10000) 

//{ 

//for  (int  i  =  0;  i  <  hits.sizeO;  i++) 

//{ 

//ODHit  odhit  =  (ODHit)hits.elementAt(i) ; 

//String  id  =  odhit. getDoc!d() ; 


//System. out. println("MAS  DOC - >id:  "  +  id); 

//System. out. println("MAS  DOC - >type:  "+ 


odhit. getDocType()) ; 

//} 

//} 

odFol  der.close() ; 
odServer.logoffO ; 
odServer.terminate() ; 

} 

catch  (ODException  e) 

{ 

System. out. println("ODException:  "  +  e) ; 

System. out. println("  id  =  "  +  e.getErrorId() ) ; 
System. out. println("  msg  =  "  +  e.getErrorMsgO) ; 
e.printStackTrace() ; 

} 

catch  (Exception  e2) 

{ 

System. out. println("exception:  "  +  e2) ; 


e2.printStackTrace() ; 

} 
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Bulk  document  retrieval  (search  with  CALLBACK) 

The  code  sample  in  Example  8-4  is  similar  to  the  logon  and  search  sample 
showed  earlier.  In  addition,  it  demonstrates  the  possibility  of  retrieving  multiple 
documents  from  an  OnDemand  server. 

To  retrieve  a  single  document  from  OnDemand,  this  requires  a  single  search  and 
retrieval  from  an  OnDemand  server.  If  several  hundred  or  several  thousand 
documents  need  to  be  retrieved,  then  a  single  search  and  retrieve  for  each 
document  would  adversely  effect  performance.  If  bulk  retrieval  of  documents  is 
required,  the  CALLBACK  API  must  be  used,  which  means  that  the  documents  to 
be  retrieved  are  collated  at  the  server  and  then  sent  back  to  the  custom  program 
as  a  single  operation.  The  code  in  Example  8-4  demonstrates  the  use  of  an 
extended  version  of  the  CALLBACK  class,  which  is  called  MyCallback,  and  it  is 
supplied  in  Example  8-5. 

Example  8-4  Code  sample  of  search  with  CallBack 

import  java.uti 1 .*; 
import  java.io.*; 
import  com.ibm.edms.od.*; 

publ ic 

class  SearchWithCallback 
{ 

public  static  void  main  (String  argv[]) 

{ 

int  rc; 

int  rumFolders; 
byte[]  data; 

Fi 1 eOutputStream  file; 

ODServer  odServer; 

ODFolder  odFolder; 

ODCriteria  odCrit; 

Vector  hits; 

ODHit  odHit; 

if  (argv. length  <  4) 

{ 

System. out. println("usage:  java  test  <server>  <user>  <pw>  <config 
dir>  [<1  ocal  server  dir>]"); 
return ; 

} 


try 

{ 

odServer  =  new  ODServer  (); 
odServer.  i  ni  ti  al  ize(argv[3] , 
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/servl ets/TestServlet") ; 


if  (argv. length  ==  4) 

odServer.logon(argv[0] , 
argv[l] , 
angv  [2] ) ; 

else  if  (argv. length  ==  5) 
odServer.logon(argv[0] , 
argv[l] , 
argv[2] , 

ODConstant.CONNECT_TYPE_LOCAL, 

0, 

argv  [4] ) ; 

numFolders  =  odServer.getNumFol ders ("C%") ; 

System. out. pri ntl n ("number  of  folders  is:  "  +  numFolders); 

odFolder  =  odServer.openFol der("Credit  Card  Statements"); 
odCrit  =  odFol der.getCri teri a("Account") ; 

//odCri  t. setOperand(ODConstant .OPBetween) ; 
odCri  t . setOperand(ODConstant .OP Li ke) ; 
odCri  t. setSearchVal ue("%") ; 

/ /ODCal 1  back  ode  =  new  ODCal 1  back ( ) ; 

MyCallback  ode  =  new  MyCallback() ; 

//ode  =  odFol der. searchWi thCal 1 back() ; 

//odFol der.searchWithCal 1 back("where  account  LIKE  ode); 

String  sql  =  "where  account  LIKE 
odFol  der.searchWithCal 1  back  (sql , 


ode) ; 

//  wait  for  the  query  to  finish 
//odc.waitForOperation() ; 

//  allow  the  user  to  cancel 

Fi  1  elnputStream  fis  =  new  FilelnputStream(FileDescriptor.in) ; 
int  i  =0; 

System. out. pri ntl n (“enter  the  number  1  to  stop  search:"); 
while  ( lode. i sDone() ) 

{ 

if  (fis.available()  !=  0) 
i  =  fis.read(); 
if  (i  ==  0x31) 

{ 

System. out .printl n("cancel 1 i ng  the  search..."); 
ode. cancel  () ; 

System. out .printl n ("search  cancel  led"); 
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// 

// 

// 

// 

// 

// 

// 

// 

// 

// 

// 

// 

// 

// 

// 

// 

// 

// 


} 

el  se 

Thread. sleep(lOO) ; 

} 

Sy stem. out. prirtln() ; 

System. out. pri rtl n ("done  searching") ; 
hits  =  odFolder.getHits() ; 

System. out. println("Number  of  hits:  "  +  hits.sizeO) ; 
if  (hits.sizeO  !=  0) 

{ 

Str i ng []  displayOrder  =  odFolder.getDisplayOrder() ; 
for  (int  i  =  0;  i  <  di spl ayOrder. 1 ength ;  i++) 

{ 

System. out. print(displayOrder[i]  +  " \t\t " ) ; 

} 

System. out. pri ntln() ; 

for  (int  j  =  0;  j  <  hits.sizeO;  j++) 

{ 

odHit  =  (ODHit)hits.elementAt(j) ; 
for  (Enumeration  e  =  odHi t .getDi spl ayVal ues () ; 
e.hasMoreElements() ; 


{ 

System. out. print((String)e.nextElement()  +  "\t\t" 

} 

System. out. println() ; 


odServer.terminate() ; 

} 

catch  (ODException  e) 

{ 

System. out. println("ODException:  "  +  e) ; 
e.printStackTrace() ; 

} 

catch  (Exception  e2) 

{ 

System. out. println("exception:  "  +  e2) ; 
e2.printStackTrace() ; 

} 


static  String  getOpName(i nt  op) 

{ 

String  s; 
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switch  (op) 

{ 

case  ODConstant.OPEqual : 
s  =  "Equal"; 
break; 

case  ODConstarit.OPNotEqual : 
s  =  "Not  Equal"; 
break; 

case  ODConstant.OPLessThan: 
s  =  "Less  Thar"; 
break; 

case  ODConstant.OPLessThanEqual  : 
s  =  "Less  Thar  or  Equal " ; 
break; 

case  ODCorstart.OPGreaterThar: 
s  =  "Greater  Thar"; 
break; 

case  ODCorstart.OPGreaterTharEqual  : 
s  =  "Greather  Thar  or  Equal"; 
break; 

case  ODCorstart.OPIr : 
s  =  "Ir"; 
break; 

case  ODCorstart.OPNotlr : 
s  =  "Not  Ir"; 
break; 

case  ODCorstart.OPLi ke: 
s  =  "Like"; 
break; 

case  ODCorstart.OPNotLi ke: 
s  =  "Not  Like"; 
break; 

case  ODCorstart.OPBetweer : 
s  =  "Betweer"; 
break; 

case  ODCorstart.OPNotBetweer: 
s  =  "Not  Betweer"; 
break; 

default: 

s  =  "Operator  urkrowr"; 
break; 

} 


returr  s; 
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CALLBACK 

The  following  code  sample  in  Example  8-5  extends  the  CALLBACK  class  and  is 
used  in  the  sample  code  that  was  shown  in  Example  8-4. 

Example  8-5  Code  sample  of  CALLBACK 


mport  java.uti 1 .*; 
import  java.io.*; 
import  com.ibm.edms.od.*; 

public  class  MyCallback  extends  ODCallback 

{ 

MyCal 1 back(0DFol der  folder) 

{ 

m_folder  =  folder; 

} 


public  void  HitHandleCallbackfint  hit,  int  off,  int  len) 

{ 

System. out. pri ntl n ("hi t:  "  +  hit  +  ",  off="+off+"  len="+len); 

} 

public  boolean  DataCallback(byte[]  data) 

{ 

System. out. pri ntl n ("data  length:  "  +  data. 1 ength) ; 
return  true; 

} 


public  boolean  Hi tCal 1 back(Stri ng  docid, 

char  type, 

Stri ng []  values) 

throws  Exception 

{ 

System. out. pri ntl n(" id  "  +  docid  +  ":  "  +  type  +  "  "); 
return  true; 

} 


ODFolder  m_folder  =  null; 

} 
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UPDATE 

The  code  in  Example  8-6  demonstrates  the  use  of  the  UPDATE  API.  In  this 
sample,  we  see  a  logon,  a  search,  and  then  using  the  UPDATE  API,  it  is  possible 
to  alter  the  index  information  for  the  hits  that  have  been  returned  from  the  search. 

Example  8-6  Code  sample  of  updating  a  document  Index 

import  java.uti 1 .*; 
import  java.io.*; 
import  com.ibm.edms.od.*; 

public  class  Logon 
{ 

public  static  void  main  (String  argv[]) 

{ 

int  rc; 

int  numFolders; 

String  info; 

String  fldname; 

ODServer  odServer; 

ODCriteria  odcrit; 

ODFolder  odfolder; 

ODHit  odhit; 

byte[]  data  =  null; 

byte[]  data2; 

Vector  hits  =  new  VectorQ; 

Hashtable  hshApproval Val s  =  null; 

if  (argv. length  <  4) 

{ 

System. out. println("usage:  java  Logon  <server>  <user>  <pw>  <config  dir> 
[<1 ocal  server  di r>] " ) ; 
return ; 

} 

try 

{ 

odServer  =  new  ODServer  (); 

System. out. pri ntl n ("cal  1  i ng  initialize  with  "+argv[3]); 
odServer. initialize(argv[3] , 

" Logon. java") ; 

System. out. println("Did  the  Initialize"); 
odServer. setServer(argv[0] ) ; 
odServer. setl)serld(argv[l] ) ; 
odServer. setPassword(argv[2] ) ; 
odServer. setPort(1445) ; 
odServer.  1 ogon  () ; 

System. out. println("Did  a  Logon"); 

odfolder  =  odServer. openFol der("Credi t  Card  Statements"); 
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odcrit  =  odfolder.getCriteria("Account") ; 

System. out. println(“Open  Folder") ; 
odcrit . setSearchVal ue( "000-000-000") ; 
odcri t . setOperand(ODCon start .OPEqual ) ; 
hits  =  odfolder.search() ; 

System. out. println("Got  Hits") ; 
odhit  =  (ODHi t) hi ts .el ementAt (0) ; 

Sys tern. out. pri n tin ("Got  odhit") ; 
info  =  odhit. getDocId() ; 

System. out. pri ntl n ("Informati on  is  "+info); 

hshApproval Val s  =  new  HashtableO; 

System. out. println("Created  new  hash  table"); 

hshApproval Val s .put ("Account" ,  "100-000-000") ; 

System. out. println("Put  values  in  the  hash  table"); 

odhit. update(hshApprovalVals) ; 

System. out. println("Updated  the  hit"); 

odServer. logoff () ; 

System. out. println("Logged  off") ; 
odServer. terminate() ; 

System. out. pri ntl n ("Termi nated  the  server  object"); 

} 

catch  (ODException  e) 

{ 

System. out. println("ODException:  "  +  e) ; 

System. out. println("  msg  =  "  +  e.getErrorMsgO) ; 
System. out. println("  msg  =  "  +  e.getErrorldO) ; 

} 

catch  (Exception  e2) 

{ 

System. out. println(“exception:  "  +  e2); 


e2.printStackTrace() ; 

} 
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8.3  Deploying  the  ODWEK  servlet 

The  servlet  that  is  supplied  with  ODWEK  can  be  deployed  on  any  of  the 
industry’s  leading  application  servers  that  support  Java  servlets.  However,  the 
method  for  deploying  servlets  varies  greatly  not  only  between  different  vendors, 
but  also  between  different  versions  and  releases  of  the  same  product.  This 
section  deals  with  deploying  the  ODWEK  servlet  within  the  environment  of  the 
IBM  WebSphere  Application  Server  (WAS)  Version  4  and  Version  5. 

The  steps  below  are  provided  as  a  supplement  to  the  section  “Deploying  the 
servlet”,  in  Chapter  2,  “Installation  and  configuration”,  in  ODWEK  Installation  and 
Configuration  Guide.  The  following  instructions  replace  points  1 , 4,  and  5,  as 
there  have  been  some  changes  in  configuration  processes  between  Versions  3, 
4,  and  5  of  WebSphere  Application  Server.  Version  3  of  WebSphere  Application 
Server  is  not  discussed  in  this  redbook,  since  the  instructions  for  this  version  are 
contained  within  the  standard  installation  documentation. 


8.3.1  Creating  the  EAR  and  WAR  files 

The  following  process  is  common  for  both  Version  4  and  Version  5  of  WebSphere 
Application  Server: 

1 .  Typically  the  Web  application  server  locates  servlet  class  files  in  the  servlet 
root  directory: 

<server_root>/l i b 

For  example,  c:\WebSphere\AppServer\l  ib 

Copy  the  ArsWWWServlet.  jar  file  to  this  directory 

2.  This  step  is  the  same  as  step  2  in  ODWEK  Installation  and  Configuration 
Guide. 

3.  This  step  is  the  same  as  step  3  in  ODWEK  Installation  and  Configuration 
Guide. 

4.  Step  number  4  onwards  in  ODWEK  Installation  and  Configuration  Guide 
should  be  replaced  by  the  following  steps. 

5.  Start  the  WebSphere  Application  Assembly  Tool: 

a.  For  Windows,  select: 

Start  — >  Programs  — >  IBM  WebSphere  — >  Application  Server  v4.0 
— >  Administrator’s  Console 

b.  For  AIX,  run  the  following  script: 

/usr/WebSphere/ AppServer/bi n/assembly . sh 
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6.  From  the  Application  Assembly  Tool  (AAT): 

a.  Click  Create  Application  Wizard. 

b.  For  display  name,  enter  OnDemand  Wek  or  whatever  you  choose  to  call  your 
application. 

c.  For  file  name,  enter  odwek.ear  or  whatever  you  choose  to  name  these 
configuration  files. 

d.  Click  Next. 

e.  Click  Next  at  the  Adding  Supplementary  Files  window. 

f.  Click  Next  at  the  Choosing  Application  Icons  window. 

g.  Click  Next  at  the  Adding  EJB  Modules  window. 

h.  Click  Next  at  the  Adding  Web  Modules  window. 

i.  Click  Next  at  the  Adding  Application  Client  Modules. 

j.  Click  Finish. 

7.  Now  a  window  opens  in  the  AAT  with  details  of  the  application  you  are 
creating  in  it: 

a.  Right-click  Web  Modules,  then  click  New. 

b.  For  file  name,  enter  odwek.war  or  whatever  you  wish  to  call  this 
configuration  file. 

c.  For  context  root,  enter  /od.  This  is  like  a  virtual  root  directory  for  this  Web 
module;  you  can  choose  any  root  location. 

d.  For  classpath,  enter  C:\websphere\appserver\lib,  the  location  of  the  JAR 
file  from  point  1 . 

e.  For  display  name,  enter  OD  WEK  Module  or  whatever  name  you  wish. 

f.  Click  OK. 

8.  Now  expand  your  OD  WEK  Module  (by  clicking  the  +). 

a.  Right-click  Web  Components  and  click  New. 

b.  For  component  name,  enter  ArsWWWServlet 

Note:  The  name  ArsWWWServlet  is  case  sensitive. 

c.  .Component  Type: 

i.  Click  Servlet. 

ii.  For  class  name,  click  Browse.  Find  the  ArsWWWServlet.  jar  file  which 
you  placed  in  the  <WebSphere  root>/lib  directory  at  point  1 . 
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iii.  Expand  the  path  COM  ->  IBM->  EDMS  ->  OD,  and  click 

ArsWWWServlet.class  file,  and  then  click  OK.  (See  Figure  8-3  for  a 
screen  display  of  the  Select  file  for  Class  Name  window.) 


Figure  8-3  Screen  display  of  selecting  the  class  file 

9.  Expand  ArsWWWServlet  Web  component,  and  do  the  following: 

a.  Right-click  Initialization  Parameters  and  click  New. 

b.  For  parameter  name,  enter  ConfigDir. 

Note:  The  name  ConfigDir  is  case  sensitive. 

c.  For  parameter  value,  enter  C:\IBM  FiTTP  Server\cgi-bin  or  wherever  you 
have  place  the  arswww.ini  file  on  your  system. 

d.  Click  OK. 

10.  Right-click  Servlet  Mapping  and  click  New. 

The  servlet  name  will  already  be  filled  in. 

You  need  to  enter  the  URL  pattern  that  you  would  like  to  use  when  calling  this 
servlet  from  within  a  Web  browser.  For  example,  arswww. 
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Click  Apply. 


Note:  The  name  chosen  here  must  be  in  /arswww/  format,  where  arswww  is 
the  name  chosen. 


1 1  .Click  File  from  the  ATT  task  bar  at  the  top,  and  then  SaveAS. 

Choose  any  location  you  wish  to  save  this  configuration,  for  example 
c:\WebSphere\AppServer\l  ib,  and  then  choose  a  name  for  the  file  such  as 

odwek.ear. 


8.3.2  Deploying  the  ODWEK  servlet  in  WAS  V4 

The  following  instructions  are  specific  to  Version  4  of  WebSphere  Application 
Server.  We  assume  that  you  have  already  followed  steps  1  through  12  in  8.3.1, 
“Creating  the  EAR  and  WAR  files”  on  page  189. 

1 .  Open  a  WebSphere  administration  console: 

Note:  At  this  point  you  should  make  sure  that  the  IBM  WebSphere  Admin 
Server  is  running. 

-  For  Windows,  select: 

Start  — >  Programs  — >  IBM  WebSphere  — >  Application  Server  V4.0 
— >  Administrator’s  Console. 

Or  from  Windows  command  prompt: 

<WAS_HOME>\bi n\admi ncl i ent . bat 

-  For  AIX,  run  the  following  command: 

/ usr /WebSphere/ AppServer/bi n/admi ncl i ent . sh 

To  administer  a  WebSphere  server  remotely,  use  the  command  with 
specific  host  name  and  port  number,  as  the  following  example: 

adminclient  webhost  900 

2.  From  the  WebSphere  administration  console,  do  the  following: 

a.  Expand  WebSphere  Admin  Domain. 

b.  Right-click  Enterprise  Applications  and  click  Install  Enterprise 
Application. 

c.  Choose  the  node  for  this  application. 

d.  Click  Browse  for  the  path  of  the  odwek.ear  file  that  you  created  above. 
Enter  an  application  name;  for  example,  ODWEK. 


192  Content  Manager  OnDemand  Guide 


e.  Click  Next. 

f.  Click  Next  at  Mapping  User  to  Roles. 

g.  Click  Next  at  Mapping  EJB  RunAs. 

h.  Click  Next  at  Binding  Enterprise  Beans. 

i.  Click  Next  at  Mapping  EJB  References. 

j.  Click  Next  at  Mapping  Resource  References. 

k.  Click  Next  at  Specify  the  Default  Datasource. 

l.  Click  Next  at  Specifying  Datasources  for  CMP  Beans. 

m.  Specify  the  virtual  host  for  your  Web  module.  For  example,  Default  Host. 
Click  Next. 

n.  Select  the  application  server  for  your  application.  For  example,  Default 
Server. 

Click  Next 

o.  Click  Finish. 

3.  Expand  Nodes. 

Right-click  your  node  and  click  Regen  WebSphere  Plugin. 

4.  Expand  Enterprise  Applications. 

Right-click  your  ODWEK  application  and  click  Start. 

5.  Stop  and  restart  the  Web  server. 

8.3.3  Deploying  the  ODWEK  servlet  in  WAS  V5 

The  following  instructions  are  specific  to  Version  5  of  WebSphere  Application 
Server.  We  assume  that  you  have  already  followed  steps  1  through  12  in  8.3.1, 
“Creating  the  EAR  and  WAR  files”  on  page  189. 

1 .  Open  a  WebSphere  administration  console. 

Note:  You  should  make  sure  at  this  point  that  the  IBM  WebSphere  Admin 
Server  is  running. 

a.  For  Windows,  do  the  following: 

Start  — >  Programs  — >  IBM  WebSphere  — >  Application  Server  V5.0 
— >  Administrator’s  Console. 

b.  For  UNIX  or  Windows  open  up  a  Web  browser  window,  enter: 
http: //<hostname>:<admi nWebPagePort>/admi n 
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Example:  http:  //I  ocal  host:9090/admi  n 

2.  From  the  WebSphere  administration  console: 

a.  In  the  tree  structure  on  the  left,  expand  Applications. 

b.  Select  Install  New  Application. 

c.  Click  Browse  and  select  the  odwek.ear  file  that  you  created  earlier. 

d.  Click  Next  at  Preparing  for  application  install. 

e.  Click  Next  at  Step  1:  Provide  options  to  perform  the  installation. 

f.  Click  Next  at  Step  2:  Map  virtual  hosts  for  Web  modules,  accept 
default_host. 

g.  At  Step  3:  Map  modules  to  application  servers,  select  an  application 
server  such  as  “serverl”,  then  select  OD  WEK  module,  and  click  Next. 

h.  Click  Finish  at  Step  4:  Summary. 

i.  On  the  confirmation  screen,  click  Save  to  Master  Configuration,  then 
click  Save. 

3.  Click  Applications,  check  the  box  next  to  the  OD  WEK  application,  and 
click  Start. 

4.  Stop  and  restart  the  Web  server. 

8.3.4  Testing  the  ODWEK  servlet 

You  are  now  finished.  To  see  if  the  servlet  works  correctly,  open  a  Web  browser 
and  type: 

http : //myserver/od/arswww 
In  this  URL: 

myserver  =  your  hostname 

od  =  your  context  root  you  defined  in  step  7 

arswww  =  your  servlet  mapping  defined  in  step  10 

You  should  see  a  screen  that  is  similar  to  that  shown  in  Figure  8-4.  If  so,  your 
servlet  works  correctly! 
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Figure  8-4  An  example  of  a  working  ODWEK  servlet 


Note:  In  the  1  ogon .  htm  file  that  you  have  in  the  document  root  of  your  Web 
server,  you  need  to  edit  the  following  line: 

<F0RM  METH0D=P0ST  ACTION="/od/arswwwll> 


The  next  step  is  to  continue  from  the  section  “Specifying  the  ARSWWW.INI  file”, 
in  Chapter  2,  “Installation  and  configuration”,  in  the  ODWEK  Installation  and 
Configuration  Guide. 
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Understanding  Xenos 


In  this  chapter  we  provide  information  on  the  Xenos  transforms  and  how  they 
relate  to  OnDemand.  We  discuss  the  various  data  transforms  that  enable 
OnDemand  to  leverage  previously  unsupported  data  types.  In  addition,  we 
discuss  some  Xenos  troubleshooting  techniques,  and  we  step  through  an 
example  of  converting  an  AFP  statement  to  Web-ready  XML. 

This  chapter  includes  the  following  topics: 

►  Xenos  and  OnDemand 

►  When  to  convert:  at  load  or  transform  time 

►  Converting  AFP  to  XML  through  ODWEK 

►  Using  the  AFP2PDF  transform  with  ARSLOAD 

►  Job  Supervisor  program 


Note:  iSeries  does  not  support  Xenos. 
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9.1  Xenos  and  OnDemand 


The  Xenos  d2e  platform  is  a  unique  component-based  solution  that  transforms 
legacy  data  and  documents  into  e-content  industry  standard  formats.  The  Xenos 
d2e  platform  is  officially  supported  with  OnDemand  Version  7.1  and  allows 
OnDemand  to  handle  data  types  that  were  previously  unsupported.  Xenos  d2e 
allows  for  the  indexing  and  loading  of  Xerox  metacode  (DJDE,  LCDS  and  mixed 
mode),  HP  PCL  and  non-indexable  IBM  AFP.  Additionally,  Xenos  allows  for 
viewing,  through  ODWEK,  directly  through  the  Web  browser.  It  does  this  by 
dynamically  converting  OnDemand  data  to  e-content  formats  such  as  XML, 
HTML,  and  PDF. 

The  Xenos  transforms  are  batch  application  programs  that  let  you  process  these 
various  input  data  types  by  converting  the  data,  indexing  on  predefined 
parameters  and  collecting  resources  to  provide  the  proper  viewing.  The  Xenos 
load  transforms  produce  three  files  (index  file,  output  file  and  resource  file)  that 
are  then  used  by  the  ARSLOAD  program  to  load  the  data  into  OnDemand.  These 
documents  are  then  available  to  users  to  search,  retrieve,  and  view. 

The  Xenos  transforms  can  be  run  either  when  loading  the  input  files  into  the 
system,  or  alternatively,  dynamically  when  the  documents  are  retrieved  via  the 
OnDemand  Web  Enablement  Kit. 

If  transforming  the  data  at  load  time,  the  following  Xenos  transforms  (Table  9-1) 
are  available: 


Table  9- 1  Available  Xenos  transforms:  transform  data  at  load  time 


FROM 

TO 

AFP 

PDF 

Metacode 

AFP 

Metacode 

PDF 

Metacode 

Metacode 

PCL 

PDF 
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If  transforming  the  data  dynamically  when  it  is  retrieved  via  ODWEK,  the 
following  Xenos  transforms  (Table  9-2)  are  available: 

Table  9-2  Available  Xenos  transforms:  transform  data  dynamically  via  OKWEK 


FROM 

TO 

AFP 

PDF 

AFP 

HTML 

AFP 

XML 

Metacode 

AFP 

Metacode 

HTML 

Metacode 

PDF 

Metacode 

XML 

Figure  9-1  shows,  at  a  high  level,  how  the  Xenos  transforms  fit  into  the 
OnDemand  environment.  This  figure  shows  the  resources  and  the  AFP, 
metacode,  or  PCL  printstream  being  fed  into  the  ARSLOAD  program.  When 
ARSLOAD  runs,  it  checks  to  see  what  indexer  to  use.  If  the  application  specifies 
Xenos,  then  the  Xenos  transforms  are  called  and  run  with  predefined  parameter 
and  script  files. 

The  output  files  produced  by  Xenos  are  handed  back  to  ARSLOAD  and  the  indexes 
and  documents  are  loaded  into  the  database  and  storage  accordingly. 
Alternatively,  if  ODWEK  is  configured  to  convert  documents  at  retrieval,  then  the 
Xenos  transforms  are  called  from  ODWEK  before  presenting  the  document  to  the 
user. 
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Figure  9- 1  How  the  Xenos  transforms  fit  into  the  OnDemand  environment 
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9.2  When  to  convert:  at  load  or  transform  time 


The  decision  of  when  to  call  the  Xenos  transforms  relies  mainly  on  the  usage  of 
the  system.  Typically,  converting  data  at  load  time  requires  more  time  to  process 
the  printstream  file,  and  converting  data  at  retrieval  time  causes  the  user  retrieval 
to  be  a  little  slower.  The  decision  may  depend  on  how  many  documents  are 
retrieved,  compared  to  how  many  are  loaded.  It  may  also  depend  on  any  legal 
requirements  about  the  format  of  stored  data.  In  the  following  sections  we  briefly 
discuss  two  different  data  types  and  the  factors  that  effect  this  decision. 


9.2.1  Xerox  metacode 

Xerox  metacode  is  designed  in  such  a  way  that  all  the  presentation  resources  are 
stored  on  the  actual  printer.  The  result  of  this  is  that  Metacode  cannot  be 
displayed  on  any  computer,  because  the  resources  cannot  exist  on  the  computer. 
Xerox  metacode  can  only  be  reprinted  to  a  printer  that  contains  the  original 
resources  for  the  document. 

If  you  wish  to  display  Xerox  metacode  through  an  OnDemand  client,  you  must 
convert  it  to  something  else.  If  you  intend  to  use  a  PC  client,  you  must  convert 
the  metacode  to  AFP  or  PDF  at  load  time  since  the  thick  client  does  not  support 
retrieval  transformation.  If  you  are  intend  to  use  OnDemand  to  reprint  the 
metacode  documents  to  the  original  metacode  printer,  then  the  documents  must 
be  stored  as  metacode  (using  the  meta2meta  transform).  Once  the  documents 
are  stored  as  metacode,  the  only  way  to  view  them  would  be  to  enable  the 
retrieval  transformation  through  ODWEK  and  convert  them  to  either  HTML,  PDF 
or  XML. 

9.2.2  AFP2PDF 

If  there  is  a  requirement  to  present  AFP  documents  in  PDF  format  over  the  Web, 
the  best  way  is  to  store  the  documents  in  their  native  format,  and  then  convert 
them  to  PDF  at  the  retrieval  time.  This  is  because  AFP  documents  are  stored 
much  more  efficiently  than  PDF.  When  multiple  AFP  documents  refer  to  the  same 
resources,  these  resources  are  stored  only  once,  and  shared  among  the  AFP 
documents. 

PDF  documents  are  completely  opposite.  All  the  resources  necessary  to  present 
a  PDF  document  are  contained  within  the  document.  The  PDF  document  will  be 
larger  than  the  original  AFP,  and  the  entire  printstream,  once  divided  up  into 
separate  customer  statements,  will  be  much  larger,  due  to  the  fact  that  each 
individual  statement  holds  all  the  resources.  See  7.2,  “Indexing  issues  with  PDF” 
on  page  1 60,  for  an  example  of  how  a  1 00k  PDF  document  can  be  indexed  as  5 
separate  PDF  documents,  with  total  of  860k  in  the  resulting  indexed  file  size. 
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Timing  is  essential  to  the  decision  as  well.  The  amount  of  time  needed  to  convert 
the  document  depends  on  how  large  it  is  and  how  many  resources  or  fonts  are 
associated  with  the  document. 


9.3  Converting  AFP  to  XML  through  ODWEK 

The  AFP  to  XML  transform  is  used  when  retrieving  AFP  documents  from  an 
OnDemand  server  through  the  use  of  ODWEK.  The  AFP  to  XML  transform 
allows  data  from  the  input  document  to  be  inserted  in  a  predefined  template  file 
using  the  Xenos  Template  Merger  facility.  This  template  file  can  be  a  standard 
XML  tagged  file  format  and  can  be  used  to  display  information  in  different  layout 
than  the  printed  page.  The  XML  file  can  then  be  used  for  online  applications  such 
as  an  online  payment  system.  Multiple  templates  can  be  used  in  a  single 
application  to  suit  the  variety  of  information  that  is  found  from  page  to  page  in  the 
input  document. 

In  this  section,  we  discuss  an  example  of  converting  an  AFP  document  to  an 
XML  document  via  the  Xenos  AFP2XML  transform  and  ODWEK.  We  walk 
through  the  steps  that  make  this  transformation  work. 

AFP2XML  example 

For  our  example,  we  use  an  AFP  customer  billing  statement  that  is  stored  in 
OnDemand.  We  would  like  our  customers  to  be  able  to  retrieve  this  document  in 
a  Web-ready  format  without  having  to  rely  on  the  AFP  Web  Viewer.  Our  Web 
developers  have  stated  that  if  they  can  extract  the  pertinent  pieces  of  information 
in  a  standard  XML  format,  they  can  use  XSL  or  CSS  to  format  the  document.  See 
Figure  9-2  to  view  the  AFP  statement  as  retrieved  from  the  OnDemand  PC  client. 

The  fields  that  we  would  like  to  extract  have  been  highlighted  with  a  box.  We 
would  like  to  extract  the  account  ID,  the  amount  due,  the  start  and  the  end  dates 
and  the  usage.  We  would  also  like  to  extract  the  current  and  previous  bill  sections 
and  all  the  charges  this  are  included  in  these  sections. 

Because  Xenos  is  doing  the  transformation  at  the  document  retrieval  time,  there 
is  no  additional  process  we  have  to  do  on  the  load  side.  The  document  has  been 
defined  into  an  OnDemand  application  group  called  xenos-xml  with  a  data  type 
of  AFP.  The  document  has  been  loaded  with  a  pagedef,  formdef,  overlay  and 
several  custom  fonts.  The  data  has  only  two  indexes  associated  with  it, 
AccountID  and  EndDate.  These  indexes  do  not  have  to  coincide  in  any  way  with 
the  Xenos  fields  we  are  extracting;  but  keep  in  mind,  the  fields  that  are  presented 
to  the  user  in  the  ODWEK  hit  list  are  the  fields  that  are  defined  in  OnDemand,  not 
Xenos.  To  ensure  that  the  document  was  loaded  correctly,  we  viewed  it  both 
through  a  PC  client  and  through  ODWEK  before  we  add  the  Xenos  processing. 


202 


Content  Manager  OnDemand  Guide 


A  BUCK  OR  TWO 
821  S  MAIN  ST 
ROCKPORT 


OFC 


TX  75080  08  A  |999  1010  6491B  |  GSW 


01-11 


]  01-17  | 


02-12-02 


READ  1179  1131 


48 


.08265 


4.0 


CURRENT  BILLING  INFORMATION 

AMOUNT  DUE 

CHARGE  FOR  GAS  USED  JAN  11  TO  JAN  17 

1%  KEMMEMER  CITY  FRANCHISE  FEE 

54  WYOMING  SALES  TAX 

CURRENT  GAS  BILLING 

#23. 07 
$.23 
#1.16 

#24.46  __ 

PREVIOUS  BILLING  AND  PAYMENT  INFORMATION 

LAST  MONTH'S  TOTAL  BALANCE 

PREVIOUS  BALANCE 

#131.34 

#131.34  _ 

INTEREST  PAID  IN  2001  #  .16 


#155.80 


CLOSING  BILL  -  EXCLUDES  ANY  APPLIANCES 

THANK  YOU  FOR  THE  OPPORTUNITY  TO  SERVE  YOU. 

IF  PAYMENT  ARRANGEMENTS  ARE  NEEDED,  PLEASE 
CONTACT  OUR  OFFICE  IMMEDIATELY.  AFTER  30  DAYS 
MOT  APPLICABLE  ALL  UNPAID  ACCOUNTS  ARE  REFERRED  TO  AN  OUTSIDE 

COLLECTION  COMPANY. 


•C07O3W681B 

SERV  ADDR: 


08  999  1010  6491B  02-12-02 


# 155. 80 


0 

0 

0 

0 


821  S  MAIN  ST  SOFC  1 

ROCKPORT  TX  75080 

83101 M35255 

**  B006 

A  BUCK  OR  TWO 
PO  BOX  825 

ROCKPORT  TX  75080-0825 


Figure  9-2  AFP  billing  statement  stored  in  OnDemand 
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As  previously  mentioned,  we  would  like  to  extract  several  fields  from  the  AFP 
document.  Once  these  fields  have  been  extracted  from  the  AFP  document,  we 
would  like  to  format  them  into  an  XML  tagged  document  with  the  following  format, 
where  xxx  is  the  value  from  the  document  (see  Example  9-1). 

Example  9-1  Coding  example  for  extracting  and  reformatting  fields 


<XML> 

<BI LLFI LE> 

<B  I L  L> 

<BILLSUMMARY> 

<ACCTI D>xxx</ ACCTI  D> 
<AMTDUE>XXX</AMTDUE> 
<STARTDATE>XXX</STARTDATE> 
<ENDDATE>XXX</ENDDATE> 
<USAGE>XXX</USAGE> 
</BILLSUMMARY> 

<CURRENT> 

<ITEM>XXX</ITEM> 
<AMOUNT>XXX</ AM0UNT> 
<ITEM>XXX</ITEM> 
<AMOUNT>XXX</ AM0UNT> 

</CURRENT> 

<PRE V I 0US> 

<ITEM>XXX</ITEM> 

<AMOUNT>XXX</AMOUNT> 

<ITEM>XXX</ITEM> 

<AMOUNT>XXX</AMOUNT> 

</PREVI0US> 

</BI LL> 

</BI LLFI LE> 

</XML> 


Following  is  a  discussion  on  how  to  implement  this  example. 

Xenos  job  parameter  file 

In  order  to  configure  ODWEK  to  run  the  Xenos  transforms,  two  input  and 
configuration  files  are  necessary,  the  job  parameter  file  (.par)  and  the  document 
manipulation  script  (.dms). 

The  Xenos  parameter  file  is  a  text  file  that  contains  parser  and  generator 
required  and  optional  parameters.  Examples  of  these  parameters  are  the  names 
of  input  and  output  files  and  the  location  of  all  document  resources,  such  as 
fonts,  pagdefs  and  formdefs.  Also  included  in  this  parameter  file  is  a  list  of  the 
fields  to  be  pulled  from  the  document  and  where  these  fields  are  located. 
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There  are  five  types  of  job-related  parameters  that  can  be  defined  in  the 
parameter  file.  They  are  organized  by  type  and  begin  with  a  section  heading.  The 
five  sections  are:  Job  Script,  Parser,  Generator,  Display  List  and  Distributor.  Each 
of  these  sections  contains  many  required  and  optional  fields  depending  on  what 
data  type  is  being  parsed  and  generated.  Refer  to  Xenos  d2e  Platform  User 
Guide,  by  Xenos  Group  Incorporated,  for  a  full  description  of  this  file. 

Table  9-3  provides  a  parameter  file  summary,  with  a  description  for  each 
parameter  section  that  is  applicable  to  our  AFP2XML  conversion. 


Table  9-3  Parameter  file  summary 


Parameter  Section 

Description 

Job  Script  (JS:) 

Indicates  the  names  and  locations  of  the  Xenos  d2e  Script 
Library.  The  Dmsl  .lib  library  is  required  and  the  conversion  will 
fail  if  this  library  is  not  defined.  This  section  also  defines  the 
variables  to  be  used  in  the  d2e  script. 

Parser 

(AFPPARSER:) 

Gives  information  about  the  incoming  document  and  how  to 
process  it.  This  section  defines  where  the  AFP  resources  (fonts, 
pagedefs,  formdefs,  overlays  and  page  segments)  are  located. 

It  also  defines  font  correlation  table. 

Generator 

(TMerge:) 

Controls  how  the  new  document  is  generated.  The  XML 
generator  uses  the  Template  Merge  Facility  which  scans  the 
template  for  variable  names  and  then  replaces  them  with 
variable  values  from  the  document.  In  our  parameter  file,  the 
PREFIX  and  SUFFIX  parameter  tell  the  template  merger  the 
characters  that  define  the  beginning  and  ending  of  the  variable 
in  the  template  file. 

Display  List 
(DUST:) 

Controls  how  special  features,  such  as  book  marking  and  URL 
links,  and  fields  are  generated.  Our  display  list  parameters  tell 
d2e  where  to  locate  each  field  in  the  input  AFP  file. 

Example  9-2  shows  the  full  content  of  our  parameter  file. 

Example  9-2  AFPS2XML_rb.par  file  content 
JS: 

FDDMSLIB  =  ‘D:\Program  Files\xenosd2e\d2ebin\dmsl .lib’ 

SCRIPTVAR  =  (‘project_path’, ’D:\d2eDevStudio\AFP2XML\’) 

SCRIPTVAR  =  (‘project_resource_path’ , ’D:\d2eDevStudio\AFP2XML\resources\’) 

AFPPARSER: 

CC  =  YES 

FDAFPFONTS  =  ‘D:\d2eDevStudio\AFP2XML\Resources\%s.fnt’ 

FDFORMDEFS  =  ‘D:\d2eDevStudio\AFP2XML\Resources\%s.fde’ 
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FDMFCT  =  ‘D:\d2eDevStudio\AFP2XML\AFP2XML.tab’ 
FDOVERLAYS  =  ‘D:\d2eDevStudio\AFP2XML\Resources\%s.ovr 
FDPAGEDEFS  =  ‘D:\d2eDevStudio\AFP2XML\Resources\%s.pde 
FDPAGESEGS  =  ‘D:\d2eDevStudio\AFP2XML\Resources\%s.psg 
FORMDEF  =  ‘flmbibiO’ 

PAGEDEF  =  ‘plmbibiO’ 

POSITION  =  WORD 

TMERGE: 

PREFIX  =  *&&’ 

SUFFIX  =  *.’ 

DLIST : 

PARMDPI  =  100 
PAGEFILTER  =  ALL 
FIELDNAME  =  ‘PAGE’ 

FIELDWORD  =  %30 
FIELDPHRASE  =  %400 

FIELDLOCATE  =  ( ‘CurrentBi 1 1 ’BILLING  INFORMATION’) 
FIELDLOCATE  =  ( ‘ EndCurrent ’, ’CURRENT  GAS  BILLING’) 
FIELDLOCATE  =  ( ‘ EndPrevi ous ’,’ PREVIOUS  BALANCE’) 

FIELDNAME  =  ‘ACCTID’ 

FIELDBOX  =  (367,78,519,98) 

FIELDWORD  =  %20 
FIELDPHRASE  =  %500 

FIELDNAME  =  ‘AMTDUE’ 

FIELDBOX  =  (714,530,816,578) 

FIELDWORD  =  %20 
FIELDPHRASE  =  %500 

FIELDNAME  =  ‘STARTDATE’ 

FIELDBOX  =  (585,81,641,99) 

FIELDWORD  =  %20 
FIELDPHRASE  =  %500 

FIELDNAME  =  ‘ENDDATE’ 

FIELDBOX  =  (652,81,714,100) 

FIELDWORD  =  %20 
FIELDPHRASE  =  %500 

FIELDNAME  =  ‘USAGE’ 

FIELDBOX  =  (730,130,769,148) 

FIELDWORD  =  %20 
FIELDPHRASE  =  %500 

FIELDNAME  =  ‘CURRBILL’ 

FIELDBASE  =  ( ‘ ’ ,41 ,  ”  , 220 ,  ”  ,800 , ’EndCurrent ’ , 30) 
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FIELDWORD  =  % 20 
FIELDPHRASE  =  %5000 
FIELDTABS  =  (0,450) 

FIELDNAME  =  ‘ PREVIOUSBILL’ 

FIELDBASE  =  ( ‘ EndCurrent ’ , -40 , ’EndCurrent ’ , 40,  ”  ,800, ’ EndCurrent ’ , 200) 
FIELDWORD  =  %20 
FIELDPHRASE  =  %5000 
FIELDTABS  =  (0,450) 

FIELDNAME  =  ‘Field’ 

FIELDBOX  =  (176,119,263,163) 

FIELDWORD  =  %20 
FIELDPHRASE  =  %500 


The  job  parameter  file  can  either  be  typed  in  manually  using  any  ASCII  editor  or 
created  graphically  using  the  d2e  Developer  Studio.  It  most  cases,  it  will  be  a 
combination  of  both.  Developer  Studio  has  a  graphical  AFP  parser  that  can 
render  the  input  file  as  a  bitmap.  This  allows  for  the  graphical  selection  of  field 
locations  for  data  extraction.  We  used  the  Developer  Studio  wizard  to  create  the 
parameter  file  and  locate  the  fields,  then  updated  this  file  manually  for  the 
resource  locations  and  the  script  variables. 

Xenos  document  manipulation  script 

The  document  manipulation  script,  or  dms,  is  the  second  file  that  ODWEK  needs 
to  run  the  Xenos  transforms.  The  dms  is  a  REXX  program  that  is  used  to 
customize  and  enhance  the  capabilities  of  the  d2e  transform  program.  The  script 
file  is  used  in  conjunction  with  the  job  parameter  file  to  determine  how  a 
particular  job  is  processed,  and  the  parameters  defined  in  the  script  override  any 
defined  in  the  parameter  file.  Refer  to  Xenos  d2e  Platform  Scripting  Reference, 
by  Xenos  Group  Incorporated,  for  a  complete  understanding  of  this  script. 

In  our  AFP2XML  transform,  the  dms  script  calls  the  AFP  parser  to  extract  the 
applicable  fields  from  the  document.  It  then  calls  the  template  merge  function 
using  a  set  of  pre-defined  template  files.  The  output  of  this  transform  is  an  XML 
tagged  text  file  with  the  information  converted  dynamically  from  the  AFP 
document  that  is  stored  in  OnDemand. 

See  Example  9-3  for  our  complete  dms  script. 

Example  9-3  AFP2XML_rb. dms  script  file  content 

/*  Document  Breaking  Script  */ 

/*  d2e  Developer  Studio  v5.1.63  */ 

/*  Project  :  AFP2XML  */ 

/*  Initialize  IDC  engine  */ 
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CALL  dm  Initial  ize 


/*  variables  */ 

TRUE  =  1 
FALSE  =  0 
doc_open  =  FALSE 

/*  Start  parsers  and  Generators  */ 

AFP_Parser_h  =  dm_StartParser(“AFP”) 

TMergel_h  =  dm_StartGenerator(“TMerge”) 

/*  Define  input  and  output  to  ODWEK  */ 

rc  =  dm_SetParm(AFP_Parser_h ,  ‘fdinput’,  inputfile); 
rc  =  dm_SetParm(TMergel_h ,  ‘fdoutput’,  outputfile); 


/*  open  generator  documents  */ 

rc  =  dm_TMergeOpen(TMERGEl_h,  outputfile,  project_resource_path  ||  “startfile.tpl”) 


SAY  “Finished  starting  up  process  “ 

/*  get  page  */ 

dlpage_h  =  dm_GetDLPage(AFP_Parser_h) 
SAY  “Parsed  page  “  dlpage_h 


DO  WHI LE (dl page_h  <>  ‘EOF’) 

/*  Get  field  values  */ 

ACCTID  =  dm_GetText(dl page_h ,”ACCTID”, 1) 

AMTDUE  =  dm_GetText(dl page_h ,”AMTDUE”, 1) 

STARTDATE  =  dm_GetText (dl page_h ,”STARTDATE”, 1) 

ENDDATE  =  dm_GetText (dl page_h .’’ENDDATE”, 1) 

USAGE  =  dm_GetText(dl  page_h, ’’USAGE”,  1) 

/*  test  for  break  and  begin  new  XML  Bill*/ 

IF  ACCTID  <>  previ ous_ACCTID  THEN  DO 
IF  doc_open  =  TRUE  THEN  DO 

rc  =  dm_TMergeWrite(TMERGEl_h,  project_resource_path  ||  “endbill . tpl ”) 
END 

previ ous_ACCTID  =  ACCTID 
doc_open  =  TRUE 
END 
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/*  write  out  Bill  Summary  Section  */ 


IF  doc_open  =  TRUE  THEM  DO 


rc  =  dm_TMergeWrite(TMERGEl_h,  project_resource_path  ||  “bill.tpl”) 

/*  This  section  parses  through  the  current  charges  section  detail  lines  and  */ 

/*  and  loads  them  into  the  xml  templast  as  the  detail  ITEM  and  detail  NUMBER  */ 

rc  =  dm_GetMultiText(dlpage_h,”currbill”,curr_cnt) 

DO  i  =  1  to  curr_cnt.O 

PARSE  var  curr_cnt.i .dm_textdata  item  ‘09’x  amount 
/*Merge  with  Template*/ 

rc  =  dm_TMergeWrite(TMERGEl_h,  project_resource_path  ||  “itemizedline.tpl”) 
END 

/*  write  out  end  of  current  section  and  beginning  of  previous  section  */ 

rc  =  dm_TMergeWrite(TMERGEl_h,  project_resource_path  ||  “endcur.tpl”) 

/*  This  section  parses  through  the  previous  charges  section  detail  lines  and  */ 
/*  and  loads  them  into  the  xml  templast  as  the  detail  ITEM  and  detail  NUMBER  */ 

rc  =  dm_GetMul tiText(dl page_h ,”previ ousbi 1 1 ”,prev_cnt) 

DO  i  =  1  to  prev_cnt.O 

PARSE  var  prev_cnt.i .dm_textdata  item  ‘09’x  amount 

rc  =  dm_TMergeWrite(TMERGEl_h,  project_resource_path  ||  “itemizedline.tpl”) 
END 
END 

/*  get  page  */ 

dlpage_h  =  dm_GetDLPage(AFP_Parser_h) 

SAY  “Parsed  page  “  dlpage_h 


END 

SAY  “Finished  processing  pages,  now  closing...” 

/*  End  last  bill  and  file  template  */ 

rc  =  dm_TMergeWrite(TMERGEl_h,  project_resource_path  ||  “endfile.tpl”) 

/*  Close  and  Finish  */ 

rc  =  dm_TMergeClose(TMERGEl_h) 
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RETURN 


The  dms  script  above  refers  to  several  template  (.tpl)  files.  These  are  the  files  that 
are  used  to  create  the  XML  output  file.  See  Example  9-4  for  the  bill,  tpl  file  that 
is  referenced.  Each  &&  begins  a  variable  to  be  replaced  with  the  actual  value  from 
the  AFP  file  before  being  inserted  into  the  output  XML  file. 

Example  9-4  Example  Template  file  bill,  tpl 
<BILLSUMMARY> 

<ACCTID>&&ACCTID.</ACCTID> 

<AMTDUE>&&AMTDUE.</AMTDUE> 

<STARTDATE>&&STARTDATE . </STARTDATE> 

<ENDDATE>&&ENDDATE.</ENDDATE> 

<USAGE>&&USAGE.</USAGE> 

</BILLSUMMARY> 

<CURRENT> 


By  creating  templates  with  as  much  variable  information  as  practical,  the 
application  runs  more  efficiently.  One  can  create  an  XML  application  where  each 
line  in  the  XML  corresponds  to  a  different  template.  However,  the  speed  of  the 
transformation  is  slowed  by  many  more  calls  to  dm_TmergeWri  te  than  necessary. 
By  making  each  template  write  more  lines  in  the  output  XML  file,  the  amount  of 
time  for  the  transformation  is  reduced.  With  careful  template  design,  d2e  platform 
applications  may  be  speed  up  considerably,  as  much  as  40%  faster. 

Configuring  ODWEK 

Once  the  transform  has  been  set  up  on  the  Xenos  side,  you  must  configure 
ODWEK  to  run  the  transform.  The  following  changes  must  be  made. 

Update  the  ARSWWW.INI  file 

The  [xenos]  section  contains  two  parameters,  InstallDir  and  ConfigFile.  The 
InstallDir  parameter  specifies  where  the  Xenos  d2e  code  is  installed.  The 
ConfigFile  parameter  specifies  the  location  of  the  configuration  file  used  by  the 
Xenos  transforms.  Our  [xenos]  section  is  as  follows: 

[xenos] 

Instal  1  Di r=D:\ Program  Fi 1 es\xenosd2e\d2ebi n 
ConfigDi r=C:\IBM  HTTP  Server\cgi-bin\arsxenos.ini 

You  must  also  update  the  Afp Viewing  parameter  in  the  [default  browser] 
section.  When  ODWEK  retrieves  an  AFP  document  from  the  OnDemand  server, 
the  value  of  this  parameter  determines  what  action,  if  any,  that  ODWEK  takes 
before  sending  the  document  to  a  Web  browser.  To  convert  AFP  documents  to 
HTML,  PDF,  or  XML  output  with  the  Xenos  transform,  specify  AfpVi  ewi  ng=Xenos 
so  that  ODWEK  will  call  the  Xenos  transform  to  convert  the  AFP  document 
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before  sending  it  to  a  Web  browser.  The  type  of  output  that  is  generated  is 
determined  by  the  value  of  the  OUTPUTTYPE  parameter  in  the  ARSXENOS.INI  file. 


Note:  This  change  affects  all  AFP  data  on  the  system;  it  is  not  limited  to 
application  group  or  folder.  If  you  want  to  override  this,  you  may  specify  the 
_afp  parameter  of  the  Retrieve  Document  API. 


Our  updated  afpviewing  parameter  is  as  follows: 

[default  browser] 

AfpViewing=xenos 

Configuring  the  arsxenos.ini  file 

The  ARSXENOS.INI  file  provides  configuration  options  for  the  Xenos  transform. 
You  typically  configure  the  ARSXENOS.INI  file  with  options  for  specific  OnDemand 
applications.  However,  you  can  also  provide  a  set  of  default  options.  The  Xenos 
transform  uses  the  default  options  when  it  converts  documents  from  applications 
that  are  not  identified  elsewhere  in  the  file. 

Below  is  our  ARSXENOS.INI  file.  The  first  section  specifies  the  application  group 
and  the  application,  separated  by  a  dash.  Our  application  group  and  application 
are  both  named  xenos-xml . 

[xenos-xml-xenos-xml] 

ParmFi le=D:\Xenos\AFP2XML_rb.par 
Seri ptFi 1 e=D:\Xenos\AFP2XML_rb.dms 

Li  cense Fi 1 e=D:\ Program  Fi 1 es\xenosd2e\l i censes\dml i c. txt 

OutputType=xml 

WarningLevel=4 


[defaul t] 

ParmFi 1 e=D:\Xenos\afp2pdf\sampl e.par 
Seri pt  Fi 1 e=D:\Xenos\noirdex.dms 

Li  cense Fi 1 e=D:\ Program  Fi 1 es\xenosd2e\l i censes\dml i c. txt 
OutputType=pdf 
WarningLevel =8 
A1 10bjects=l 
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The  ParmFile  parameter  identifies  the  full  path  name  of  the  file  that  contains  the 
parameters  that  are  used  by  the  Xenos  transform  to  convert  the  document.  This 
points  to  our  afp2xml_rb.par  file  discussed  earlier. 

The  ScriptFile  parameter  identifies  the  full  path  name  of  the  file  that  contains  the 
script  statements  that  are  used  by  the  Xenos  transform  to  create  the  output  file. 
This  points  to  our  afp2xml_rb.dms  script  discussed  earlier. 

The  LicenseFile  parameter  identifies  the  full  path  name  of  a  valid  license  file  that 
you  obtained  from  Xenos. 

The  OutputTvpe  parameter  determines  the  type  of  conversion  that  the  Xenos 
transform  performs.  If  the  input  document  is  AFP,  you  can  set  this  parameter  to 
HTML,  PDF,  or  XML.  If  the  input  document  is  metacode,  you  can  set  this 
parameter  to  AFP,  HTML,  PDF,  or  XML.  Since  we  are  converting  from  AFP  to 
XML,  our  parameter  is  XML. 

The  AllObjects  parameter  determines  how  ODWEK  processes  documents  that 
are  stored  as  large  objects  in  OnDemand.  If  you  specify  0  (zero),  then  ODWEK 
retrieves  only  the  first  segment  of  a  document.  If  you  specify  1  (one),  then 
ODWEK  retrieves  all  of  the  segments  and  converts  them  before  sending  the 
document  to  the  viewer. 


Note:  If  you  enable  large  object  support  for  very  large  documents,  then  your 
users  may  experience  a  significant  delay  before  they  can  view  the  document. 


The  WarningLevel  parameter  determines  how  ODWEK  handles  return  codes 
from  the  Xenos  transform.  The  Xenos  transform  sets  a  return  code  after  each 
document  is  converted.  Use  this  parameter  to  specify  the  maximum  return  code 
that  ODWEK  will  consider  to  be  good  and  will  send  the  converted  document  to 
the  viewer. 

Viewing  the  XML  document 

Once  the  parameter  file,  the  dms  script,  and  all  the  configuration  files  have  been 
updated,  you  can  select  a  document  and  see  the  Xenos  output.  When  we  log  on 
to  ODWEK  and  open  the  xenos-xml  folder,  we  get  a  hit  list  of  all  the  AFP 
documents.  When  we  select  a  document,  ODWEK  recognizes  the  document  as 
AFP  and  checks  the  ARSWWW.INI  file  to  see  how  to  present  the  AFP  data.  The 
afpviewing  parameter  tells  ODWEK  to  execute  a  Xenos  transform,  so  ODWEK 
checks  the  [xenos]  section  to  determine  the  location  of  the  ARSXENOS.  INI  file. 
ODWEK  then  looks  at  the  ARSXENOS.  INI  file  to  determine  the  parameter  and 
script  files  to  use.  The  Xenos  AFP2XML  transform  is  then  invoked  and  the  XML 
document  is  sent  to  the  browser.  You  can  see  the  XML  output  in  Figure  9-3. 
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Figure  9-3  AFP  document  presented  in  XML  format  sample 
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Now,  let’s  change  the  afpviewi ng  parameter  in  the  ARSWWW.INI  file  back  to 
plug-in.  With  just  that  one  change,  the  AFP  document  is  now  presented  to  the 
browser  in  its  native  format  and  displayed  with  the  AFP  Web  Viewer;  see 
Example  9-4. 


©]  Displaying  page  1  of  1  £  Internet 


Figure  9-4  AFP  document  displayed  in  its  native  format  with  AFP  Web  Viewer 
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This  XML  document  is  presented  with  standard  tags  and  can  be  displayed  using 
a  variety  of  XML  display  methods.  We  created  a  simple  Cascading  Style  Sheet 
(CSS)  definition  file,  and  with  a  few  minor  changes  to  the  template,  this  XML  file 
can  now  be  presented  to  a  browser  in  a  Web-ready  format. 

We  created  a  CSS  definition  file  that  takes  each  parameter  from  the  XML  tagged 
file  and  presents  it  to  a  browser.  This  file  is  named  di  sp_bi  1 1 .  css.  In  order  to  call 
this  CSS  file  and  tell  the  browser  to  associate  it  with  the  XML  file,  we  had  to  make 
a  change  to  the  template  file  that  is  called  from  our  dms  script.  To  tell  the  browser 
to  use  the  di  sp_bi  1 1 .  css  file  to  present  the  XML  file,  we  have  added  two  lines  to 
the  startf i  1  e .  tpl  template  file,  which  now  looks  as  follows: 

<?xml  versi on= 1 1.0 1 ?> 

<?xml -styl esheet  type=" text/css"  href =" D:\Xenos\di sp_bi 1 1 .css"?> 

<BI LLFI LE> 

<BILL> 

Now  when  we  click  the  document  in  the  hit  list,  the  browser  sees  the  first  two 
lines  in  the  XML  file  that  tell  the  browser  to  present  the  document  with  the  style 
sheet.  The  document  now  appears  as  shown  in  Figure  9-5. 


File  Edit  View  Favorites  Tools  Help 

vr1  Back  -  -  £  [?)  4f  Q  Search  f%i Favorites  .Jjj'Media  y)  |  £jj  gf  fib] 

Address  |  s)  http :  //cmdemo/cgi-bin/arswww .  cgi?h=template .  htm&a=r&d=5 143-5 144-51 45-QBA 1  - 1 FAAA-0-6345-0- 18358-85-79-2- 1  -0-%5E 


CHARGE  FOR  GAS  USED  JAN  11  TO  JAN  17 

$23.07 

1%  KEMMEMER  CITY  FRANCHISE  FEE 

$.23 

5%  WYOMING  SALES  TAX 
$1.16 

CURRENT  GAS  BILLING 

$24.46 


LAST  MONTH'S  TOTAL  BALANCE  $131.34  PREVIOUS  BALANCE  $131.34 


Figure  9-5  Sample  document  output  using  XML  and  CCS 
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Example  9-5  is  the  di  sp_bi  1 1 .  css  file  that  we  are  using  to  display  the  document. 

Example  9-5  disp_bill.css  Cascading  Style  Sheet  file 
ACCTID 

{display:  block; 

background-image:  url (acctid.gif) ; 
background-repeat:  no-repeat; 
margin-left:  lOOpx; 
margin-right:600px; 
background-color:  ICCCCCC; 
font-size:  16pt; 
font-weight:  bold; 
border:  thin  ridge; 
padding-left:  120px 
} 


AMTDUE 

{display:  block; 

background-image:  url (amtdue.gif) ; 
background-repeat:  no-repeat; 
margin-left:  lOOpx; 
margin-right:600px; 
background-color:  ICCCCCC; 
font-size:  16pt; 
font-weight:  bold; 
border:  thin  ridge; 
padding-left:  200px 
} 

STARTDATE 

{display:  block; 

background- image:  url (strtdate.gi f) ; 
background-repeat:  no-repeat; 
margin-left:  lOOpx; 
margin-right:600px; 
background-color:  ICCCCCC; 
font-size:  16pt; 
font-weight:  bold; 
border:  thin  ridge; 
padding-left:  220px 
} 

ENDDATE 

{display:  block; 

background- image:  url (enddate.gi f) ; 
background-repeat:  no-repeat; 
margin-left:  lOOpx; 
margin-right:600px; 
background-color:  ICCCCCC; 
font-size:  16pt; 
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font-weight:  bold; 
border:  thin  ridge; 
padding-left:  220px 
} 

USAGE 

{display:  block; 

background- image:  url (usage. gi f) ; 
background-repeat:  no-repeat; 
margin-left:  lOOpx; 
margin -right:600px; 
background-color:  ICCCCCC; 
font-size:  16pt; 
font-weight:  bold; 
border:  thin  ridge; 
padding-left:  245px 
} 

CURRENT  {  display:  block; 
margin-top:  80px; 
border-top:  2px  groove  blue; 
border-bottom:  2px  groove  blue; 
margin-bottom:  30px; 
background- image:  url (paybi 1 1 .gi f) ; 
background-repeat:  no-repeat; 
background-position:  50%  100%} 

CURRENT  ITEM  {display:  block; 
font-weight:  bold} 

CURRENT  AMOUNT {  display:  inline} 

PREVIOUS  ITEM, PREVIOUS  AMOUNT 
{  display:  inline; 
font-weight:  bold; 
padding-right:  20px; 
padding-left:  30px 


Troubleshooting  ODWEK  /  Xenos 

By  enabling  debugging  mode  in  ODWEK,  you  can  view  any  error  or  success 
message  that  come  from  ODWEK  or  Xenos.  To  turn  logging  on,  make  the 
following  changes  to  the  ARSWWW.INI  file. 

[DEBUG] 

log=l 

1 ogdi r=D:\odwek\l  oggi ng 
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In  this  example,  1  og=l  turns  debugging  on  (1  og=0  turns  it  off)  and  1  ogdi  r  is  the 
directory  where  the  log  file  is  created.  The  log  file  is  named  arswww.log. 


9.4  Using  the  AFP2PDF  transform  with  ARSLOAD 

The  previous  example  discussed  a  transform  that  occurred  on  the  retrieval  side. 
Xenos  can  also  perform  the  transform  during  ARSLOAD,  before  the  print  file  gets 
loaded  to  OnDemand.  In  addition  to  transforming  the  data,  Xenos  can  also 
provide  indexing  and  resource  collection  capabilities  as  well  as  print  file 
segmentation  into  logical  documents  or  statements. 

To  enable  the  Xenos  transforms  on  the  load  side,  you  must  specify  the  indexer  to 
be  Xenos  in  the  OnDemand  application.  When  ARSLOAD  sees  an  indexer  of 
Xenos,  it  calls  the  Xenos  transform  with  the  parameter  and  script  files  that  are 
specified  in  the  application.  Xenos  creates  three  files  to  be  sent  back  to  ARSLOAD, 
the  index  file,  the  output  file  and  a  resource  file.  ARSLOAD  uses  these  files  to 
update  the  database  and  object  server. 

When  using  Xenos  to  parse  the  input  printstream  file,  it  is  possible  to  allow  the 
transform  to  pull  out  indexes  from  the  file  and  to  split  the  file  into  logical 
documents.  When  doing  this,  it  is  important  to  define  the  same  database  fields  in 
both  Xenos  and  OnDemand.  Xenos  provides  a  .  ind  file  that  contains  each  field 
and  the  value.  If  OnDemand  receives  too  many  indexes  or  not  enough  indexes, 
or  if  the  indexes  are  a  different  data  type,  the  load  will  fail. 

This  example  discusses  the  conversion  of  an  AFP  document  to  an  Adobe  PDF 
format  before  getting  it  loaded  into  OnDemand.  This  PDF  format  can  be  viewed 
through  the  OnDemand  client  and  the  ODWEK  client  with  the  Adobe  Acrobat 
software.  We  first  used  Xenos  Developer  Studio  to  select  field  locations  from  the 
document  and  define  document  splitting  rules.  We  also  created  a  script  file 
(Example  9-6  on  page  220)  and  parameter  file  (Example  9-7  on  page  224).  The 
parameter  file  defines  the  parser  and  generator  that  we  use.  It  also  contains  the 
locations  of  the  AFP  resources  to  be  used  to  convert  the  file,  and  the  rules  for 
creating  the  PDF  file.  Finally,  the  script  defines  the  data  to  be  used  as  the  index 
for  the  document.  In  this  example,  we  only  define  one  index  field:  Name. 

We  created  an  application  and  application  group  called  xenos-pdf.  We  are 
loading  AFP  data,  but  because  Xenos  converts  it  to  PDF  before  it  gets  loaded, 
we  define  the  View  Information  data  type  to  be  PDF.  In  the  Indexer  Information 
page,  the  indexer  is  defined  as  Xenos  -  this  directs  OnDemand  to  call  the  Xenos 
transforms.  When  you  use  Xenos  as  the  indexer,  there  are  only  4  parameters  in 
the  indexing  details:  Xenos  parameter  file,  Xenos  script  file,  Xenos  License  file, 
and  warning  level.  See  our  application  as  set  up  in  Figure  9-6. 
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Update  an  Application 


Load  Information  |  Logical  View  Fields  |  Logical  Views  |  Print  Options 
General  View  Information  Indexer  Information 


Parameters  Source 
(•  Keyboard 

Indexer  | Xenos  _^j 

C  Parameter  File  Modify...  | 

Details...  1 

1 

3] 


Edit  Indexer  Parameters 


d 


OnDeiiajicDCeiiosPaniiFile=D :  \xenos\a£p2pci£\a£p2pd£_sairi)le  .par 
OnDemandXenosScriptFile=D :  \xenos\a£p2pd£\a£p2pd£_sair^le .  dms 

OnDemandXenosLicenseFile=D :  \Program  Files \xenosd2e\licenses\devstudio .  IBliOnDe 
0nDemandXenosWarn±n(jLevel=4 


d 


iH 


iL 


dJ 


OK 


Cancel 


Apply 


Help 


Figure  9-6  Application  indexing  parameters  for  Xenos 


When  defining  the  Xenos  parameter  script  files  in  the  application,  there  are  two 
methods:  the  details  method  and  the  filename  method.  In  our  example 
(Figure  9-6),  we  used  the  filename  method,  where  we  point  to  the  full  path  of  the 
files.  Using  the  filename  method  is  a  way  to  be  able  to  reuse  the  same  files 
between  multiple  applications  and  is  a  better  method  of  separating  the 
OnDemand  and  Xenos  administration. 


Optionally,  you  can  paste  the  entire  script  and  parameter  file  directly  into  the 
indexing  parameters  screen.  Using  the  detail  method  allows  the  OnDemand 
administrator  to  view  the  Xenos  parameters  without  the  need  to  access  any  other 
system.  It  is  also  a  way  to  manage  multiple  versions  of  scripts  and  applications. 
There  is  never  any  question  about  which  application  is  using  which  script  files.  If 
the  printstream  data  changes,  a  new  application  can  be  created  with  a  new  script 
and  parameter  file  included.  When  using  the  detail  method,  the  parameter  file 
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details  must  be  included  between  a  OnDemandXenosParmBegin  tag  and  an 
OnDemand XenosParmEnd  tag.  The  script  details  must  be  included  within  the 
OnDemandXenosScriptBegin  tag  and  the  OnDemandXenosScriptEnd  tag. 

Either  of  these  methods  works. 

When  calling  the  transform  from  ARSLOAD,  be  sure  not  to  have  any  input  or  output 
file  names  hard  coded  in  the  script  or  parameter  file.  If  you  do  have  an  input  file 
listed  in  the  fdinput  or  inputfile  parameters,  the  Xenos  transform  runs  with  a 
return  code  of  0;  but  it  will  not  be  processing  the  data  that  ARSLOAD  is  sending.  If 
you  have  the  output  files  defined  in  f doutput,  outputf  i  1  e,  i  ndexf  i  1  e  or 
resourcefile  parameters,  Xenos  also  runs  fine,  but  ARSLOAD  gives  a  message 
saying  “Output/Indexer  file  was  not  created  Indexing  Failed”. 

Any  error  messages  that  come  from  the  Xenos  transforms  are  populated  into  the 
System  Log  and  can  viewed  in  message  number  87,  failed  load.  All  success 
details  that  come  from  the  Xenos  transform  can  be  viewed  in  message  number 
88,  successful  load. 

Example  9-6  AFP2PDF_sampte.dms  script 

TRUE  =  1; 

FALSE  =  0; 

call  dm_Initialize 

par_h  =  dm_StartParser(Parser) ; 
gen_h  =  dm_StartGenerator(Generator) ; 

rc  =  dm_SetParm(par_h ,  'fdinput',  inputfile); 

/*  start  the  DASD  Distriubtors  */ 
dasd_h  =  dm_StartDistributor("DASD") ; 
index_h  =  dm_StartDistributor("DASD") ; 

/*  open  output  and  index  files  */ 

rc  =  dm_DASDOpen (dasd_h ,  1 {G ROUP  FI LENAME } 1 outputfi 1 e) ; 
rc  =  dm_DASDOpen(index_h,  indexfile  ); 

/*  initialize  */ 
do  i  =  1  to  NumberOfFi el ds 
f i el dval uesave. i  =  "" 
if  Break. i  \=  "no"  &  Break. i  \=  "NO"  then 
do 

Break. i  =  "yes" 
end 
end 

file_open  =  FALSE 
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save_BytesWri tten  =  0 
crl f  =  1 OdOa 1 X 

/*  write  preamble  to  the  index  file  */ 

rc  =  dm_DASDWrite(index_h,  "COMMENT:  OnDemand  Generic  Index  File  Format"); 
rc  =  dm_DASDWrite(index_h,  "COMMENT:  This  file  has  been  generated  by  the  xenos  process"); 
dt  =  DATE('N'); 
ts  =  TIME('N'); 

rc  =  dm_DASDWrite(index_h,  "COMMENT:"  dt  ts  ); 

rc  =  dm_DASDWri te ( i ndex_h ,  "COMMENT:"  ); 

rc  =  dm_DASDWri te ( i ndex_h ,  "CODEPAGE : 819 " | |crlf  ); 

dlpage  =  dm_GetDLPage(par_h) ; 

do  while(dlpage  \=  'EOF') 
if  file_open  =  FALSE  then  do 
select 

when  generator  =  'PDF'  then 

rc  =  dm_PDFGenOpen(gen_h,  ' { GROUP  FI LEENTRY } 1 outputf i 1 e) ; 
when  generator  =  'AFP'  then 

rc  =  dm_AFPGenOpen(gen_h,  ' { GROUP  FI LEENTRY } 1 outputf i 1 e) ; 
when  generator  =  'META'  then 

rc  =  dm_METAGenOpen (gen_h ,  1 { GROUPFI LEENTRY } 1  output fi 1 e) ; 
otherwise  do 

say  'Invalid  generator' 
return  12 
end 
end 

if  rc  =  0  then  do 
file_open  =  TRUE 
end 
end 

do  i  =  1  to  NumberOf Fi el ds 

fieldvalue.i  =  dm_GetText(  dlpage,  field. i.  First  ) 
end 

docbreak  =  0 

do  i  =  1  to  NumberOf Fi el ds 
if  fieldvalue.i  \=  ""  then  do 

/*  if  there  is  no  previous  value,  save  the  current  value  */ 
if  f i el dval uesave. i  =  ""  then  do 
fieldvaluesave.i  =  fieldvalue.i 
end 
el  se 

/*  if  there  is  a  previous  value,  see  if  the  new  value  is  different  */ 
if  fieldvaluesave.i  \=  fieldvalue.i  then  do 
if  Break. i  =  "yes"  then 
docbreak  =  1 
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end 

end 

end 

if  docbreak  =  1  then  do 
sel ect 

when  generator  =  'PDF'  then  rc  =  dm_PDFGenClose(  gen_h  ) 
when  generator  =  'AFP'  then  rc  =  dm_AFPGenClose(  gen_h  ) 
when  generator  =  'META'  then  rc  =  dm_METAGenClose(  gen_h  ) 
end 

file_open  =  FALSE 

/*  write  out  index  values  to  the  index  file  */ 
do  i  =  1  to  NumberOf Fi el ds 
fi  el  d_name  =  "GROUP_FIELD_NAME: 11 1  |  fi  el  d.  i 
rc  =  dm_DASDWri te(  index_h,  field_name  ) 
field_value  =  ,,GROUP_FIELD_VALUE: 11 1 1  fi  el  dval  uesave.  i 
rc  =  dm_DASDWri te(  index_h,  field_value  ) 
end 

/*  replace  index  values  with  the  new  values  */ 
do  i  =  1  to  NumberOf Fi el ds 
if  fieldvalue.i  \=  1111  then  do 
fieldvaluesave.i  =  fieldvalue.i 
end 
end 

rc  =  dm_DASDSi ze(dasd_h) 

BytesWritten  =  dm_size 
length  =  BytesWritten  -  save_BytesWritten 
offset  =  BytesWritten  -  length 
save_BytesWri tten  =  BytesWritten 

group_offset  =  "GR0UP_0FFSET: 11 1  |  offset 
rc  =  dm_DASDWrite(  index_h,  group_offset  ) 
group_length  =  "GROUP_LENGTH: " | | length 
rc  =  dm_DASDWrite(  index_h,  group_length  ) 
group_f i 1 ename  =  "GROUP_FILENAME: " | | outputf i  1  e 
rc  =  dm_DASDWrite(  index_h,  group_fi 1 ename | | crl f  ) 

select 

when  generator  =  'PDF'  then 

rc  =  dm_PDFGenOpen (gen_h ,  ' { GROUPFI LEENTRY } 1 outputf i 1 e) ; 
when  generator  =  'AFP'  then 

rc  =  dm_AFPGenOpen (gen_h ,  ' {GROUPFI LEENTRY} 'outputfile); 
when  generator  =  'META'  then 

rc  =  dm_METAGenOpen(gen_h ,  ' { GROUP  FI LEENTRY } 'outputfile) ; 
end 

if  rc  =  0  then  do 
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file_open  =  TRUE 
end 

end  /*  end  docbreak  =  1  */ 
select 

when  generator  =  'PDF'  then  rc  =  dm_PDFGenWrite(gen_h,  dlpage  ); 

when  generator  =  'AFP'  then  rc  =  dm_AFPGenWrite(gen_h,  dlpage  ); 

when  generator  =  'META'  then  rc  =  dm_METAGenWrite(gen_h,  dlpage  ); 
end 

dlpage  =  dm_GetDLPage(par_h) ; 
end 

if  file_open  =  TRUE  then  do 
select 

when  generator  =  'PDF'  then  rc  =  dm_PDFGenClose(  gen_h  ) 

when  generator  =  'AFP'  then  rc  =  dm_AFPGenClose(  gen_h  ) 

when  generator  =  'META'  then  rc  =  dm_METAGenCl ose(  gen_h  ) 
end 
end 

/*  write  out  final  index  values  to  the  index  file  */ 
do  i  =  1  to  NumberOfFi el ds 
f i el d_name  =  "GROUP_FIELD_NAME: " | | fiel d. i 
rc  =  dm_DASDWrite(  index_h,  field_name  ) 
field_value  =  "GROUP_FIELD_VALUE: " | | f i el dval uesave.  i 
rc  =  dm_DASDWrite(  index_h,  field_value  ) 
end 

rc  =  dm_DASDSi ze(dasd_h) 

BytesWritten  =  dm_size 
length  =  BytesWritten  -  save_BytesWri tten 
offset  =  BytesWritten  -  length 
save_BytesWri tten  =  BytesWritten 

group_offset  =  "GR0UP_0FFSET: " | | offset 
rc  =  dm_DASDWrite(  index_h,  group_offset  ) 
group_length  =  "GROUP_LENGTH: " | | 1 ength 
rc  =  dm_DASDWrite(  index_h,  group_l ength  ) 
group_fi lename  =  "GROUP_FILENAME: " | | outputfi 1 e 
rc  =  dm_DASDWrite(  index_h,  group_f i 1 ename  ) 

rc  =  dm_DASDCl ose(  dasd_h  ) 
rc  =  dm_DASDCl ose(  index_h  ) 
return ; 
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Example  9-7  AFP2PDF_sample.par  parameter  file 
/*  Xenos  Job  Parameter  file  */ 

JS: 

/*  DM  Script  Library  -  XG  supplied  functions  */ 
fddmslib  =  ‘d:\program  fi 1 es\xenosd2e\d2ebi n\dmsl . 1 ib’ 

scriptvar=(‘Parser’ ,  ‘AFP’) 
scriptvar=(‘Generator’ ,  ‘PDF’) 
scriptvar=(‘NumberOfFields’,  1) 
scriptvar=(‘Field.l’, ’Name’) 


AFPDL-AFPP: 

/*  AFP  Parser  Options  */ 
formdef  =  f la  10 1 1 1 
pagedef  =  pla06462 
CC  =  on 
trc  =  off 
startpage  =  0 
stoppage  =  0 
native  =  no 
position  =  word 

/*  File  Defs  */ 

FDpagesegs  =  ‘D:\xenos\afp2pdf\Resources\%s.psg’ 
FDafpfonts  =  ‘D:\xenos\afp2pdf\Resources\%s.fnt’ 
FDpagedefs  =  ‘D:\xenos\afp2pdf\Resources\%s.pde’ 
FDformdefs  =  ‘D:\xenos\afp2pdf\Resources\%s.fde’ 
FDoverlays  =  ‘D:\xenos\afp2pdf\Resources\%s.ovr’ 

FDfontcor  =  ‘D:\xenos\afp2pdf\Resources\master.tab’ 
FDResGrpOut  =  ‘D:\xenos\afp2pdf\0utput\sample.res’ 
ResGrpOption  =  (FormDefs,  PageSegs,  Overlays) 

PDFGEN-PDFOUT : 

/*  PDF  Out  Generator  Options  */ 

/*  output  file  name  being  set  in  the  script  */ 

offset  =  (0,0) 

scaleby  =  100 

border  =  NONE 

Compress  =  (NONE, NONE, NONE) 
orient  =  AUTO 

PDFAuthor  =  ‘Xenos  Group’ 

PDFOpenAct  =  ‘/Fi tH  800’ 

BMOrder  =  (AsIs,AsIs,AsIs) 
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AFPDL-DLIST : 
parmdpi  =  300 
pagefilter  =  all 
resfilter  =  all 


FieldName  =  (PAGE) 
FieldWord  =  (20,  and,  %20) 
FieldPhrase  =  (%100) 
FieldPara  =  (%500) 


/*  extract  name  */ 

FieldLocate  =  (‘InsName’,  ‘Insured’) 
FieldName  =  (‘Name’) 

FieldBase  =  (‘InsName’,  +275, 

-35, 

*=’,  +800, 

+30) 


FieldWord  =  (20,  and,  %20) 
FieldPhrase  =  (%500,  OneSpace) 
FieldPara  =  (%500) 


9.5  Job  Supervisor  program 

The  Job  Supervisor  (JS)  program  is  the  main  Xenos  transform  program.  There 
are  three  methods  for  calling  this  program.  The  first  method  is  to  allow  the 
ARSLOAD  program  to  call  JS  to  transform  a  complete  data  file  at  load  time,  as  was 
discussed  in  the  previous  section.  This  method  uses  the  input  file  from  the 
arsload  command  and  send  the  output  back  to  arsload  when  the  transform  has 
completed  —  at  which  time,  OnDemand  loads  the  data. 

The  second  method  is  to  allow  the  Web  Enablement  Kit  to  call  the  JS  program 
when  a  document  is  requested  from  ODWEK.  This  calls  JS  with  one  specific 
document,  allow  the  document  to  be  transformed,  then  send  the  transformed 
data  back  to  the  browser.  This  method  was  discussed  in  9.3,  “Converting  AFP  to 
XML  through  ODWEK”  on  page  202. 

The  final  method  of  calling  the  JS  program  is  from  a  command  line.  This  may  be 
a  useful  troubleshooting  technique,  as  it  runs  Xenos  without  any  connection  to 
OnDemand  and  allows  you  to  pinpoint  any  problems.  The  JS  program  can  also 
be  used  to  print  the  locations  of  text  strings  found  on  the  pages  of  an  input  file. 
These  text  locations  are  necessary  for  defining  indexes  and  locating  extraction 
data.  Using  Developer  Studio  is  a  graphical  method  of  defining  data  locations 
and  is  a  much  simpler  technique. 
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A  brief  note  about  Developer  Studio  here  is  appropriate.  Developer  Studio  allows 
for  defining  fields  from  the  document  to  be  used  for  indexes.  There  are  two  types 
of  fields  that  are  of  interest,  the  absolute  field  and  the  relative  field.  The  absolute 
field  is  defined  by  the  x  and  y  coordinates  of  a  box  around  the  text  of  interest.  The 
relative  field  is  useful  for  extracting  data  that  has  different  positions  in  a  page,  but 
can  be  found  in  relation  to  another  piece  of  text  on  the  page.  For  more 
information  about  using  Developer  Studio,  refer  to  Xenos  d2e  Developer  Studio 
User  Guide,  by  Xenos  Group  Incorporated. 

When  running  JS  from  a  command  line  to  convert  data,  Figure  9-7  shows  the 
syntax. 


— JS — partus — filename — report — filename — scriptvar-inputfile — filename- 

» — scri  ptvar-outputfi  1e- — -fi  leName — scri  ptvar-indexf  i  le- — fi  leName - 

» — scri  ptvar-resourcef  i  1  e- — fi  leliame —  1  i  cense- — fi  lename - 


Figure  9-7  JS  program  syntax 

Flere,  -parms  is  a  file  that  contains  the  JS  parameter  (.  par)  file  and  the  JS  script 
(.dins)  file.  All  the  parameters  are  required,  but  you  may  put  the  i nputfile, 
outputfi  1  e  and  resourcefi  1  e  parameters  in  the  .  par  or  the  .dms  file  instead  of  in 
the  command  line. 

We  ran  the  JS  program  from  the  command  line  with  our  parameter  file  and  script 
file  from  the  previous  AFP2PDF  example  to  ensure  the  index  file  was  being 
created  correctly.  We  did  this  before  setting  up  the  PDF  application  group,  just  to 
ensure  Xenos  was  working  correctly  before  wrapping  the  ARSLOAD  around  it. 
ARSLOAD  runs  the  same  command  with  the  same  syntax.  Our  command  was  as 
shown  in  Example  9-8. 

Example  9-8  Running  the  JS  program  from  a  command  line 

js  -parms=”D:\Xenos\afp2pdf\parms_afp2pdf” 
-report=”D:\Xenos\afp2pdf\output\sampl  e. rep” 

-scriptvar=inputfi 1 e=”D:\Xenos\afp2pdf\i nput\afp2pdf_sampl  e.afp” 
-scriptvar=indexfi 1 e=”D:\Xenos\afp2pdf\output\afp2pdf_sampl e. i nd” 

-scri ptvar=outputf i le=”D:\Xenos\afp2pdf\output\afp2pdf_sample. out” 
-scriptvar=resourcefi 1 e=”D:\Xenos\afp2pdf\output\afp2pdf_sampl e. res” 
-licersefi 1 e=D:\Program  Fi 1 es\xenosd2e\l icenses\dml ic.txt 
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Here,  our  parms_afp2pdf  (Example  9-9)  contained  the  .par  and  .dms  filenames. 

Example  9-9  parms_afp2pdf  file 

fdjobparm=’ D:\xenos\afp2pdf\afp2pdf_sample. par’ 
fddmsscript= ’D:\xenos\afp2pdf\afp2pdf_sample.dms’ 


This  transform  creates  a  .  i  nd  file  in  the  format  of  the  generic  indexer  parameter 
file.  This  file  can  then  be  loaded  into  OnDemand  with  the  ARSLOAD  command. 
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10 


User  exits 


In  OnDemand,  it  is  possible  to  use  exit  points  in  order  to  customize  and  enhance 
the  standard  functionality  within  the  product.  This  chapter  introduces  the  variety 
of  exit  points  within  the  OnDemand  product.  By  using  actual  working  sample 
code,  we  present  some  examples  of  the  types  of  operations  and  enhanced 
functions  that  are  possible. 

The  following  topics  are  covered  in  this  chapter: 

►  AC  IF  exits 

►  Security  exit 

►  System  Log  exit 

►  Print  exit 

►  ARSYSPIN  feature  and  COBOL  input  exit  for  z/OS 
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10.1  Introduction 


A  user  exit  is  a  point  during  processing  that  enables  you  to  run  a  user-written 
program  and  return  the  control  of  processing  after  your  user-written  program 
ends.  All  of  the  exits  within  the  OnDemand  product  are  server  exits.  These  are 
the  OnDemand  exit  points: 

►  Indexing  exits  -  ACIF 

►  System  logging  exit 

►  Print  exit 

►  Security  exit 

►  Fax  options  exit 

►  Storage  management  external  cache  exit 

►  Tablespace  create  exit 

►  Load  exit 

►  Permissions  exit 

In  order  to  explain  what  can  be  done  using  these  exit  points,  we  offer  examples 
for  the  first  four  exits  listed  above. 


Note:  For  OnDemand  for  Multiplatforms,  the  arscsxit.h  file  in  the 
/usr/lpp/ars/exits  directory  provides  some  documentation  for  the  last  six  exits, 
with  sample  source  code. 


OnDemand  provides  data  at  each  exit  that  can  serve  as  input  to  the  user-written 
programs.  Using  these  exits,  it  is  possible  to  do  functions  such  as  e-mailing 
based  on  events  in  the  system,  updating  index  values  via  a  print  request,  clean 
up  data  as  it  is  loaded  into  OnDemand,  and  access  external  security  managers. 
There  are  infinite  examples  that  could  be  provided  here  for  what  is  possible  from 
the  OnDemand  exits;  we  provide  some  samples  here  that  act  as  a  guide  for 
creating  customized  user  exits  programs. 


10.2  ACIF  exits 

The  ACIF  user  exit  is  a  point  during  the  ACIF  processing  where  the  control  is 
handed  from  ACIF  over  to  a  user-written  program.  After  the  user-written  program 
finished,  the  control  is  handed  back  to  ACIF.  There  are  four  points  during  ACIF 
processing  at  which  user  programs  can  be  configured:  input,  indexing,  output 
and  resource. 


Note:  The  ACIF  exits  are  called  for  each  and  every  input,  indexing,  output, 
and  resource  record.  They  are  not  limited  to  being  called  only  once  per  file. 
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In  Multiplatforms,  ACIF  user  exits  must  be  written  in  C.  In  z/OS,  ACIF  user  exits 
must  be  written  in  COBLOL  or  ASSEMBLER.  ACIF  exits  does  not  exist  in  iSeries. 

Refer  to  IBM  Content  Manager  OnDemand  for  Multiplatforms  -  Indexing 
Reference,  SC27-0842  and  IBM  Content  Manager  OnDemand  for  z/OS  and 
OS/390  -  Indexing  Reference,  SC27-1375  for  detail  documentation  on  each  of 
these  exit  points. 


10.2.1  Input  record  exit 

ACIF  provides  the  input  record  exit  that  enables  you  to  add,  delete  or  modify 
records  in  the  input  file  before  they  are  processed  by  ACIF.  The  primary  purpose 
of  this  exit  is  to  be  able  to  modify  input  records  before  ACIF  sees  them.  The  input 
exit  can  be  used  to  insert  indexing  information.  More  common  uses  are  to 
remove  null  characters,  truncate  records,  add  carriage  control,  and  change  code 
pages.  In  general,  indexer  parameters  should  reflect  what  the  input  record  looks 
like  after  the  input  exit  has  be  executed.  The  only  exception  is  the  FILEFORMAT 
indexer  parameter,  which  should  correspond  to  the  input  record  before  it  is 
passed  to  the  input  exit.  For  example,  if  an  ASCII  stream  type  file  is  being  loaded, 
FILEFORMAT=STREAM,(NEWLINE=x’OA’)  parameter  should  be  used,  not 
(NEWLINE=x’25’),  an  EBCDIC  stream  delimiter.  Otherwise,  ACIF  will  not  pass 
the  correct  record  to  the  apka2e  input  exit. 

OnDemand  provides  three  input  record  exits.  You  can  either  use  these  as 
samples  to  build  from,  or  you  can  compile  them  and  run  them  as  is.  These 
programs  are  documented  in  OnDemand  Indexing  References  and  are 
described  briefly  in  the  following  sections. 

apka2e 

This  exit  translates  data  that  is  encoded  in  ASCII  (code  set  IBM-850)  into 
EBCDIC  (code  set  IBM-037).  There  is  a  much  wider  selection  of  EBCDIC  coded 
fonts  than  there  are  ASCII,  and  many  customer  find  it  easier  to  use  supplied  IBM 
ones  than  to  create  their  own  character  sets  and  code  pages.  In  order  to  use 
these  pre-defined  EBCDIC  coded  fonts,  the  data  must  be  in  EBCDIC. 

When  using  this  exit,  you  must  manually  change  your  indexing  parameters 

►  Change  CPGID=500 

►  Change  the  HEX  codes  for  the  triggers  and  fields  from  ASCII  to  EBCDIC.  We 
used  Hexedit  to  determine  the  new  EBCDIC  values  and  typed  them  in  by 
keyboard  edit  into  the  parameter  file.  If  you  do  not  do  this,  you  will  get  an  ACIF 
return  code  - 1 6,  stating  that  it  could  not  find  triggerl  or  any  fields.  See 
section  10.2.5,  “Debugging  user  exit  programs”  on  page  236  for  further 
information  on  howto  update  indexing  parameters. 
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ascnnp 

This  exit  program  is  used  when  the  data  does  not  contain  carriage  control;  rather, 
it  contains  “PC  style”  carriage  returns  and  form  feeds:  X’ODOA’  and  X’ODOC’.  This 
IBM  provided  program  will  transform  the  ASCII  data  stream  into  a  record  format 
that  contains  a  carriage  control  character  in  byte  0  of  every  record.  This  exit  does 
the  following: 

►  Inserts  a  new  page  command  (X’31’)  at  the  top  of  the  first  page. 

►  Replaces  the  ASCII  carriage  return  (X’OD’)  with  an  ASCII  new  line  (X’20’). 

►  Replaces  the  ASCII  form  feed  (X’OC’)  with  an  ASCII  new  page  command 
(X’31  ’). 

►  Leaves  X’OA’ in  the  file. 


Note:  Because  asci  inp  inserts  carriage  control  characters  in  byte  0  of  your 
document,  and  leaves  the  X’OA’,  it  may  change  the  position  of  the  triggers  and 
fields.  If  you  use  this  exit,  you  will  need  to  add  1  to  the  column  offsets  for  the 
triggers  and  fields. 


asciinpe 

This  exit  example  performs  a  combination  of  the  previous  two  exits.  It  converts 
the  data  from  ASCII  to  EBCDIC  and  it  also  inserts  EBCDIC  carriage  control 
characters.  Refer  to  the  asci  i  npe .  c  source  code  for  full  documentation  on  this 
sample  program. 


10.2.2  Index  record  exit 

The  index  record  exit  allows  you  to  modify  or  ignore  the  records  that  ACIF  writes 
in  the  index  object  file.  The  program,  specified  in  the  ACIF  indxexit  parameter, 
will  receive  control  just  before  a  record  is  written  to  the  index  object  file.  The  user 
written  program  can  tell  ACIF  to  use  the  record,  not  to  use  the  record,  or  perform 
some  sort  of  editing  on  the  record  before  inserting  into  the  index  object  file. 

A  good  use  of  this  program  could  be  for  an  application  that  needs  to  pull  an  index 
from  a  source  other  than  the  document.  The  application  group  could  be  set  up 
with  a  default  index,  then  the  user  exit  program  could  grab  the  appropriate  index 
from  this  secondary  source  and  replace  the  default  value  that  was  in  the  index 
record.  The  record  would  then  be  sent  back  to  ACIF. 

Another  example  is  to  modify  the  format  of  an  existing  index.  Example  10-1  is  a 
sample  index  exit  C  program  to  update  the  date  format  from  mmddyy  to  mm/dd/yy. 
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Example  10-1  Sample  AC  IF  index  exit  program 


Idefine  _c_APKIND 


/*  */ 

/*  MODULE  NAME:  UPDDATE.C  */ 

/*  */ 

/*  SYNOPSIS:  ACIF  Sample  Index  Exit  */ 

/*  */ 

/*  */ 

/*  DESCRIPTION:  This  module  converts  the  date  format  */ 

/*  from  mmddyy  to  mm/dd/yy  before  adding  the  */ 

/*  record  to  the  index  object  file  */ 

/*  */ 


linclude  "apkexits.h"/*  standard  acif  exit  header  file  */ 
long 

INDXEXIT (  INDXEXIT_PARMS  *exitstruc  ) 

{ 

i  nt  i ; 


if  (  exi tstruc->eof  !=  IDX_EOFLAG  ) 

{ 

^•kiekick'k'k'kic'kic'k'kic'k'k'k'k'k'k'k'k'k'k'k'k'k'k'kic'k'k'k'k'kick'kick'k'k'k'k'k'k'k'k^ 

/*  Look  for  TLE  with  attribute  name  "mmddyy"  */ 

^•kiekickic'k'k'k'k'k'k'k'k'k'k'k'kick'k'k'k'k'k'k'k'k'k'kic'k'k'k'k'k'k'k'k'k'k'k'k'k'k'kick^ 


(exi  tstruc->record[13] 
(exi tstruc->record[14] 
(exi tstruc->record[15] 
(exi tstruc->record[16] 
(exi tstruc->record[17] 
(exi tstruc->record[18] 

{ 


0x6D)  && 
0x6D)  && 
0x64)  && 
0x64)  && 
0x79)  && 
0x79)) 


J  Jciticicicicicicicjcicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicic 

/*  TLE  length  is  now  40  (was  30)  * 

^•kick'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'kic'k'k'k'kick'k'k'k'k'k'kic'k 

exitstruc->record[  2]  =  0x28; 

^•kick'k'k'k'kicic'kic'k'kicic'kickicick'k'k'kic'kicic'k'kic'kicick'k'k'k'k'k'kic'k'kic'kick 

/*  Attribute  value  count  is  now  12  (was  10)  * 

^ick'k'kick'k'k'k'k'k'k'kick'kickicick'kic'kic'k'kic'kicickic'k'kic'k'kick'kic'k'kick'k'k 

exitstruc->record[19]  =  OxOC; 

^•kiekickic'k'k'k'k'k'k'k'k'k'k'k'kicic'kicic'k'k'k'kic'kick'kicic'kic'k'kick'k'k'k'k'k'kic'k 


/ 

/ 

/ 


/ 

/ 

/ 


/ 
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/*  Relocate  attribute  qualifier  triplet  X 1 80 '  */ 

/ifkic'k'kic'kicic'k'kic'kick'kickicickicickicic'kic'kicick'kickic'k'kic'kicic'k'kickic'k/ 


for  ( i  =40 ;  i >30 ;  i— ) 

exitstruc->record[i]  =  exitstruc->record[i-2] ; 

^•kiekickic'k'k'k'k'k'k'k'k'k'kic'kidc'k'k'k'k'k'k'kic'k'kic'kicic'kic'k'kic'k'kic'k'k'k'kic'k^ 

/*  Charge  mmddyy  to  mm/dd/yy  */ 

^•kiekick'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'kic'kick'k'k'k'kick'kic'k'k'k'k'k'k'k'k'k^ 


exi  tstruc->record[30] 
exi  tstruc->record[29] 
exi  tstruc->record[28] 
exi tstruc->record[27] 
exi  tstruc->record[26] 
exi  tstruc->record[25] 


exitstruc->record[28] ; 
exitstruc->record[27] ; 
0x61; 

exitstruc->record[26] ; 
exitstruc->record[25] ; 
0x61; 


^•kick'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k  J 

/*  record  length  has  increased  to  41  (was  39)  */ 

^•kick'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k  j 


exi tstruc->recordl n  =  41; 

} 

exi tstruc->request  =  IDX_USE; 

} 


return(  0  ) ; 

} 


10.2.3  Output  record  exit 

The  output  record  exit  allows  you  to  modify  or  ignore  the  records  ACIF  writes  to 
the  output  document  file.  The  program  is  invoked  by  the  ACIF  outexi  t  parameter 
and  it  gives  control  to  the  user  program  before  a  record  (structured  field)  is 
written  to  the  output  (.out)  file. 

Example  1 0-2  shows  a  sample  output  exit  program  that  deletes  records  from  the 
output  file.  This  program  is  checking  each  structured  field  to  determine  if  it  is  an 
AFP  record  or  not.  If  the  record  does  not  begin  with  a  Hex  5A,  the  exit  program 
will  tell  ACIF  not  to  use  this  record. 
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Example  10-2  Sample  AC  IF  output  exit  program 


Idefine  _c_ACCT_OUT 

^  ic^icicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicicieicieieicicicicicicieicicieicicieicicicic  ^ 

/*  */ 

/*  MODULE  NAME:  ACCT_0UT.C  */ 

/*  */ 

/*  */ 

/*  SYNOPSIS:  ACIF  Output  Exit  */ 

/*  */ 

/*  DESCRIPTION:  This  program  will  delete  all  non-AFP  records  (or  */ 

/*  records  that  do  rot  begin  with  X(5A)  from  the  */ 

/*  output  object  before  giving  control  back  to  ACIF  */ 

/*  */ 

/*  Standard  acif  exit  header  file  */ 

^'kick'k'kick'kick'kickick'kickicic'kicickicickic'kicickick'kick'k'k'k'kic'k'kickick^ 

*1 

linclude  "acctexits.h" 


long 

ACCTOUT (  OUTEXIT_PARMS  *exitstruc  ) 

{ 


^•kic'k'k'k'k'k'k'k'k'kic'kic'k'k'k'k'k'k'k'k'k'k'k'k'k'k'kic'k'kic'k'kic'k'k'k'k'k'k'k'k'k'kic'k'k'k'k'kic'k'k'k'kic'k'k'k'k'k'k'k'k'k'k'k'k'k'k  J 

/*  Delete  all  records  from  the  output  that  do  not  begin  with  Hex  1 5A 1  */ 

^icic'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'kic'kicic'kic'k'k'k'k'kic'k'k'k'kic'k'k'k'k'kic'k'k'k'kic'k'k'k'k'k'k'k'k'k'kic'k'k'k  J 


if(  exi tstruc->eof  !=  ACIF_E0F  ) 

{ 

if(  exi tstruc->record[0]  ==  0x5A  ) 
exi tstruc->request  =  ACIFJJSE; 
el  se 

exi tstruc->request  =  ACIF_DELETE; 

} 


return(  0  ) ; 

} 


10.2.4  Resource  exit 

The  ACIF  resource  exit  is  provided  to  filter  specific  resources  from  the  resource 
file.  If  you  want  to  exclude  a  specific  type  of  resource  such  as  an  overlay,  you  can 
control  this  with  the  ACIF  restype  parameter. 

This  exit  is  best  used  to  control  resources  at  the  file  name  level.  For  example, 
assuming  that  you  intended  to  send  the  output  of  ACIF  to  PSF  and  you  only 
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wanted  to  send  those  fonts  that  were  not  shipped  with  the  PSF  product,  you 
could  code  this  exit  program  to  contain  a  table  of  all  fonts  shipped  with  PSF  and 
filter  those  from  the  resource  file.  The  program  invoked  at  this  exit  is  defined  in 
the  ACIF  resexit  parameter. 

ACIF  does  not  invoke  the  exit  for  the  following  resource  types: 

►  Page  definitions:  The  pagedef  is  a  required  resource  for  processing  line-mode 
application  output  and  is  never  included  in  the  resource  file. 

►  Form  definitions:  The  formdef  is  a  required  resource  for  processing  print  files. 
If  you  do  not  want  the  formdef  to  be  included  in  the  resource  file,  specify 
restype=none  or  explicitly  exclude  it  from  the  restype  list. 

►  Coded  fonts:  If  you  specify  MCF2REF=CF,  ACIF  includes  coded  fonts.  By  default, 
(MCF2REF=CPCS),  ACIF  processes  coded  fonts  to  determine  the  names  of  the 
code  pages  and  font  character  sets  they  reference.  This  is  necessary  in 
creating  Map  Coded  Font-2  (MCF-2)  structured  fields. 


10.2.5  Debugging  user  exit  programs 

Sometimes  when  working  with  exits,  it  is  necessary  to  know  how  the  exit  has 
changed  your  data  before  you  actually  load  it.  A  method  of  doing  this  is  to  set  up 
ACIF  to  run  standalone  (not  called  from  arsload). 

To  set  up  ACIF  to  run  standalone,  create  an  indexing  parameter  file  with  no 
triggers,  fields  or  indexes  defined.  Include  your  input  file  and  the  exit  routine  in 
the  parameter  file.  Then,  run  arsaci  f  from  a  command  line,  pointing  to  this 
parameter  file.  You  can  also  direct  the  output  to  a  file.  Example  10-3  shows  our 
ACIF  parameter  file,  parmfile.  The  command  to  run  standalone  ACIF  is  as 
follows: 

arsacif  parmdd=parmf i 1 e  >  ‘output  filename’ 

This  will  write  the  output  of  ACIF,  including  the  input  exit  processing,  to  the  output 
file  where  you  can  inspect  it  and  make  sure  it  did  what  you  expected.  You  can 
also  use  this  output  file  in  the  graphical  indexer  to  index  your  post-exit  file,  as  the 
exit  routine  may  change  the  location  of  your  triggers  and  fields. 

Another  method  is  to  run  arsload  with  the  -i  option  which  runs  indexing  only. 
This  will  create  the  .ind  and  .out  files  for  you  to  view. 

Example  10-3  ACIF  parameter  file 
CC=N0 

C0NVERT=N0 
CPGI D=850 
MCF2REF=CPCS 
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TRC=NO 

FILEFORMAT=STREAM, (NEWLINE=X’OA’) 

DCFPAGENAMES=NO 

UNIQUEBNGS=YES 

INPUTDD=C:\temp\bi 1 1 i ng_i nput.txt 

INDEXDD=C: \temp\bi 1 ling_input.txt. ind 

RESOBJDD=C : \temp\bi 1 1 i ng_i nput .  txt . res 

OUTPUTDD=C:\temp\bi 1 1 i ng_i nput.txt. out 

IMAGEOUT=ASIS 

INSERTIMM=NO 

RESTYPE=NONE 

INPEXIT=C:\Program  Files\IBM\OnDemand  for  WinNT\exits\acif\asciinp.dll 


To  make  the  debug  output  more  readable,  include  INPUTDD,  INDEXDD, 
RESOBJDD,  and  OUTPUTDD  parameters  in  the  parameter  file  (as  shown  in  the 
example  given). 


Note:  It  is  very  important  to  specify  the  complete  path  in  the 
inpexit/indexit/resexit/outexit  parameter.  There  is  nothing  more  frustrating  than 
trying  to  debug  an  exit  that  never  gets  called  because  another  exit  with  the 
same  name  is  being  invoked  due  to  the  PATH  environment  variable. 


10.3  System  log  exit 

The  OnDemand  system  log  is  a  tool  used  by  administrators  to  maintain  a  log  of 
all  of  the  activity  which  occurs  within  an  OnDemand  server.  Each  operation 
performed  by  a  user  which  involves  a  connection  to  the  OnDemand  server  can 
be  logged.  The  detail  which  is  captured  within  the  system  log  can  be  configured 
so  that  only  certain  messages  are  retained  while  others  can  be  discarded. 

The  system  log  exit  is  supplied  in  arslog  file  which  resides  in  the  bin  directory  of 
the  OnDemand  install  root  for  each  respective  platform.  If  the  arslog  file  is 
opened  in  a  text  editor,  you  will  notice  that  it  is  simply  comments  which  provide  a 
brief  description  of  the  exit  and  the  order  of  the  parameters  which  OnDemand 
hands  to  this  exit.  By  default,  the  system  log  exit  is  not  initialized  within 
OnDemand,  and  so  if  you  were  to  edit  the  arslog  file  to  capture  information,  the 
exit  would  not  be  executed  automatically.  In  order  to  activate  the  system  log  exit, 
you  must  do  the  following: 

1 .  Start  the  administrative  client  and  logon  to  the  server  which  you  intend  to  use 
the  system  logging  exit. 

2.  Right-click  the  name  of  the  server  in  the  list  and  select  System  Parameters 
as  shown  in  Figure  10-1. 
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Figure  10-1  Select  On  Demand  system  parameters 

3.  To  choose  a  User  Exit  Logging  option,  check  the  option. 


Tip:  The  arslog  exit  file  is  run  by  the  same  user  that  owns  the  arssockd 
process  that  is  calling  this  exit.  A  common  reason  for  getting  no  response  from 
this  exit  is  access  permissions  on  either  the  arslog  file  itself  or  files  and 
directories  that  are  being  accessed  within  arslog. 


OnDemand  provides  an  exit  for  each  of  the  four  system  logging  event  points. 
These  exits  allow  you  to  filter  the  messages  and  take  action  when  a  particular 
event  occurs.  For  example,  you  can  provide  a  user  exit  program  that  sends  a 
message  to  a  security  administrator  when  an  unsuccessful  logon  attempt  occurs. 


10.3.1  System  log  exit  samples 

In  order  to  demonstrated  some  of  the  most  common  uses  for  the  system  log  exit, 
this  section  provides  three  typical  examples.  For  the  sake  of  simplicity,  we  have 
not  demonstrated  the  system  log  exits  across  all  supported  platforms.  We 
recognize  that  the  scripting  languages  between  platforms  do  vary,  but  the 
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principles  which  we  describe  here  are  uniform  across  all  supported  platforms  - 
only  the  syntax  differs.  The  samples  provided  are  a  mixture  of  UNIX,  Windows 
and  z/OS. 

Capturing  failed  logon  attempts  (AIX) 

Example  10-4  is  an  extract  from  a  very  simple  system  logging  exit  which 
captures  message  code  31  (a  failed  logon  attempt)  and  writes  the  user  ID  which 
was  used  and  some  information  about  the  network  address  of  this  user  to  a  file. 
In  this  case,  the  file  name  is  a  combination  of  the  system  date  and  the  string 
f ai  1  edl  ogon .  1  og.  This  system  log  exit  will  write  all  of  the  failed  logon  attempts  for 
each  day  out  to  a  file  which  can  then  be  sorted  and  analyzed  by  other  utilities  to 
alert  for  possible  security  risks. 

Example  10-4  Capturing  failed  logon  attempts  (AIX) 

#  $1  -  OnDemand  Instance  Name 

#  $2  -  Time  Stamp 

#  $3  -  Log  Identifier 

#  $4  -  Userid 

#  $5  -  Account 

#  $6  -  Severity 

#  $7  -  Message  Number 

#  $8  -  Message  Text 

# 

case  $7  in 

31)  echo  $4  $8  »  /home/archi ve/'date  +"%d-%m-%Y" ' f ai 1 edl ogon .  1 og; ; 

*)  echo  $@  >  /dev/nul 1 ; ; 

esac 

exit  0 


For  the  exit  sample  provided  in  Example  10-4,  we  have  also  provided  a  small 
sample  of  what  the  output  of  this  exit  might  look  like  as  in  Example  1 0-5.  For 
instance,  you  can  see  in  the  output  provided  that  several  unsuccessful  attempts 
have  been  made  from  the  same  machine  and  different  user  ID  have  been  used  at 
each  attempt.  In  this  example,  by  adding  parameter  2  ($2)  to  the  output  and 
re-sorting  the  file,  we  could  further  establish  the  time  of  these  attempts. 

Example  10-5  Sample  exit  output 

ADMIN  Failed  login:  GB55102K3.boulder.ibm.com  9.17.46.21 
MARTIN  Failed  login:  GB55102K3.boulder.ibm.com  9.17.46.218 
FRED  Failed  login:  GB55102K3.boulder.ibm.com  9.17.46.218 
USER1  Failed  login:  GB55102K3.boulder.ibm.com  9.17.46.218 

USER2  Failed  login:  GB55102K3.boulder.ibm.com  9.17.46.218 

USER3  Failed  login:  GB55102K3.boulder.ibm.com  9.17.46.218 
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Sending  an  e-mail  when  a  load  fails  (Windows) 

On  Windows  machines,  the  system  log  exit  file  is  called  arslog.bat  rather  than 
arslog  due  to  the  batch  file  naming  convention  used  in  the  Windows 
environment.  Example  10-6  is  a  system  log  exit  extracted  from  a  Windows 
machine  which  collects  a  variety  of  information  when  the  exit  receives  the 
Message  Number  88  (the  message  code  for  a  failed  load  process).  In  this 
example,  once  the  necessary  information  is  collected  and  stored  to  the 
failedload.txt  file,  then  the  file  is  e-mailed  to  the  OnDemand  administrator.  The 
e-mail  program  used  in  this  case  is  the  same  command  line  e-mailer  that  is 
shipped  with  the  E-mail  Notification  services  offering  although  any  e-mail 
program  will  be  sufficient. 

Example  10-6  Sending  an  e-mail  when  a  load  fails  (Windows) 

REM 

REM  %1  -  OnDemand  Instance  Name 

REM  %2  -  Time  Stamp 

REM  %3  -  Log  Identifier 

REM  %4  -  Userid 

REM  %5  -  Account 

REM  %6  -  Severity 

REM  %7  -  Message  Number 

REM  %8  -  Message  Text 

REM 

if  (%7) ==( "88 " )  echo  Message  -  %8  >  c:\temp\failedload.txt 
REM  ========================================== 

REM  ==  Message  number  88  is  a  failed  load  ==== 

REM  ========================================== 

echo  Time  -  %2  »  c:\temp\failedload.txt 

echo  UserlD  -  %4  »  c:\temp\failedload.txt 

echo  Account  -  %5  »  c:\temp\failedload.txt 

echo  Severity  -  %6  »  c:\temp\failedload.txt 

"d:\program  f i 1 es\i bm\ondemand  for  wi nnt\emai 1 \arssendmai 1 "  -b 

c:\temp\failedload.txt  -f  ondemand-server@ibm.com  -h  d06m!032  -s  %8  -t 

admi ni strator@ondemand.com 

REM  ====================================================== 

REM  ==  arssendmail  is  a  simple  command  line  e-mail  tool  == 

REM  ====================================================== 

fi 


Notifying  another  system  when  a  load  has  completed  (AIX) 

This  sample  was  used  in  a  live  production  environment  where  the  number  of  load 
jobs  that  were  sent  to  OnDemand  needed  to  be  controlled  so  that  the  next  load 
job  would  only  be  sent  when  the  pervious  one  had  completed  successfully.  In  this 
case,  this  is  because  there  was  a  limited  amount  of  disk  space  in  the  location  on 
the  OnDemand  server  where  the  load  files  were  received  from  the  remote 
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machine  and  that  the  load  files  were  extremely  large.  Example  10-7  shows  how 
the  exit  collects  virtually  all  of  the  available  information  when  it  received  a 
message  number  of  87  (a  successful  load).  This  information  is  then  used  as  the 
input  for  another  script  which  notifies  the  remote  machine  that  the  load  is 
complete  and  the  next  report  file  can  be  sent. 

Example  10-7  Controlling  load  jobs  (AIX) 

#  $1  -  OnDemand  Instance  Name 

#  $2  -  Time  Stamp 

#  $3  -  Log  Identifier 

#  $4  -  Userid 

#  $5  -  Account 

#  $6  -  Severity 

#  $7  -  Message  Number 

#  $8  -  Message  Text 

# 


#  if  [  $6  =  ''3"  ] ;  then 

#  print  $@  »  /home/archive/InfoMsg.l og 

#  fi 

case  $7  in 

# 

#  msg  num  87  is  a  successful  load 

# 

87)  echo  "Instance  :  $1"  »  /arsacif/companyx/arslog.out 
echo  "Time  Stamp  :  $2"  »  /arsacif/companyx/arslog.out 
echo  "Log  Identifier  :  $3"  »  /arsacif/companyx/arslog.out 
echo  "Userid  :  $4"  »  /arsacif/companyx/arslog.out 
echo  "Account  :  $5"  »  /arsacif/companyx/arslog.out 
echo  "Severity:  $6"  »  /arsacif/companyx/arslog.out 
echo  "Message  Number:  $7"  »  /arsacif/companyx/arslog.out 
echo  "Message  Text  :  $8"  »  /arsacif/companyx/arslog.out 
/arsacif/companyx/control_file.scr  »  /arsacif/companyx/arslog.out 


esac 

exit  0 


Important:  For  a  guide  for  the  codes  for  each  of  the  message  types  logged  in 
the  system  log,  refer  to  Chapter  2,  “Common  Server  Messages”,  in  IBM 
Content  Manager  OnDemand  -  Messages  and  Codes,  SC27-1 379.  For 
example,  message  number  88  is  listed  as  ARS0088I. 
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10.3.2  System  log  exit  on  z/OS 

OnDemand  can  be  configured  to  record  information,  warning,  and  error 
messages.  OnDemand  can  be  set  up  to  send  these  exit  to  the  system  log  exit 
named  the  ARSLOG  installation  exit.  The  implementation  of  the  system  log  exit  on 
z/OS  is  different  from  those  on  Multiplatforms.  Like  other  z/OS  exits,  it  uses  the 
MVS  Dynamic  Exit  Facility. 

The  configuration  of  the  system  log  exit  is  done  with  the  administrator  client  by 
using  the  Systems  Parameters  dialog  box.  After  selecting  the  system 
parameters,  as  in  Figure  10-2,  the  dialog  box  appears. 


Figure  1 0-2  Selection  dialog  box  for  user  exit  select 

Make  the  sections  for  the  system  logging,  and  set  up  the  exit  itself. 

Example  10-8,  routes  the  messages  to  the  system  log  with  the  WTO  Macro. 
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Example  10-8  System  log  exit  setup  sample 


ARSLOG  title  'Issue  a 

message  to  syslog1 

00010000 

******************  START  OF  MODULE  SPECIFICATIONS  ******************* 

00020000 

* 

* 

00030000 

* 

* 

00040000 

* 

==>  OD/ 390 

-  5655-H39  <== 

* 

00050007 

* 

* 

00060000 

* 

Module  Name: 

ARSLOG 

* 

00070000 

* 

* 

00080000 

* 

Descriptive  Name: 

Issue  a  message  to  syslog 

* 

00090000 

* 

* 

00100000 

* 

Status: 

Version  ?  Release  ? 

* 

00110000 

* 

* 

00120000 

* 

Function: 

This  routine  issues  a  message  to  the  SYSLOG 

* 

00130000 

* 

* 

00140000 

* 

Copyright: 

5655-H39  (C)  Copyright  IBM  Corp.  2000 

* 

00150007 

* 

Licensed  Materi al s-Property  of  IBM 

* 

00160000 

* 

See  Copyright  instructions. 

* 

00170000 

* 

* 

00180000 

* 

Notes: 

* 

00190000 

* 

* 

00200000 

* 

Restri cti ons : 

None 

* 

00210000 

* 

* 

00220000 

* 

Regi ster 

* 

00230000 

* 

Convention : 

R1  points  to  the  Parameter  list 

* 

00240000 

* 

R12  base  register 

00250000 

* 

* 

00260000 

* 

Patch  Label : 

PSPACE 

* 

00270000 

* 

* 

00280000 

* 

Input: 

Parameter  list  pointed  to  by  Register  1 

* 

00290000 

* 

Parameter  list  contains  addresses  of: 

* 

00300000 

* 

-  message  length 

* 

00310000 

* 

-  message  text 

* 

00320000 

* 

* 

00330000 

* 

Output: 

None 

* 

00340000 

* 

* 

00350000 

* 

Return  codes: 

* 

00360000 

* 

* 

00370000 

* 

NORMAL: 

R15  =  return  code  from  WTO 

* 

00380000 

* 

* 

00390000 

* 

Exits: 

Return  to  caller  via  BR  14 

* 

00400000 

* 

* 

00410000 

* 

External  References: 

* 

00420000 

* 

* 

00430000 

* 

Change  Activity: 

See  below 

* 

00440000 

* 

* 

00450000 

* 

Ver  Rel  Mod  Date  Description  of  Change 

* 

00460000 

* 

* 

00470000 
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*  0?  0? 

00  04/05/00  Release  ?.? 

*  00480000 

* 

*  00490000 

********************  END  OF  MODULE  SPECIFICATIONS  *******************  00500000 

ARSLOG 

csect 

00510000 

ARSLOG 

rmode 

any 

00520000 

ARSLOG 

amode 

31 

00530000 

usi  ng 

*,rl5 

00540000 

b 

pastcopy 

00550000 

dc 

C1 ARSLOG  &sysdate 

00560000 

dc 

C 1 5622-662  (C)  COPYRIGHT  IBM  CORP.  2000' 

00570000 

dc 

CALL  RIGHTS  RESERVED1 

00580000 

dc 

C1 LICENSED  MATE RIALS -PROPERTY  OF  IBM1 

00590000 

pastcopy 

ds 

Oh 

00600000 

stm 

14,12, 12(rl3) 

00610001 

lr 

rl2,rl5 

00620000 

lr 

r2,rl 

00630000 

usi  ng 

pi i st, r2 

00640000 

drop 

rl5 

00650000 

usi  ng 

ARSLOG, rl2 

00660000 

storage  OBTAIN, 1 ength=workl ,loc=ANY,cond=YES 

00670000 

1  tr 

rl5,rl5 

00680000 

jnz 

bagi  t 

00690000 

st 

rl3,4(,rl) 

00700000 

st 

rl,8(,rl3) 

00710000 

lr 

rl3,rl 

00720000 

usi  ng 

workarea, rl3 

00730000 

* 

00740000 

*  Determine  the  message  length 

00750005 

* 

00760000 

sir 

rl.rl 

Number  of  bytes 

00770005 

1 

rl5,msgtxta 

get  starting  address 

00780005 

nul 1 oop 

ds 

Oh 

00790006 

cl  i 

0(rl5) ,x'00' 

Is  it  zero? 

00800005 

je 

nomore 

Yes  -  quit 

00810005 

la 

rl,l(,rl) 

Bump  count 

00820005 

la 

rl5,l(,rl5) 

bump  address 

00830005 

j 

nul 1 oop 

And  try  next 

00840005 

nomore 

ds 

Oh 

00850005 

lr 

r3,rl 

Save  length  of  message 

00860005 

mvc 

msgtxt+2(3) ,=c'XXX 

1  Set  the  prefix 

00870007 

la 

rl4,msgtxt+5 

Start  to  place  number 

00880005 

1 

rl5,msgnum 

Get  start  of  message  number 

00890005 

numl oop 

ds 

Oh 

00900005 

cl  i 

0(rl5) ,x' 00 1 

Null? 

00910005 

je 

nomove 

00920005 

mvc 

0(0, rl4), 0(15) 

move  it 

00930005 

la 

rl4,l(,rl4) 

next  destination 

00940005 

la 

rl5,l(,rl5) 

next  source 

00950005 

j 

numl oop 

go  do  next 

00960005 
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nomove  ds 

Oh 

00970005 

1 

rl5,sev 

Get  severity 

00980005 

cl  i 

0(rl5) ,c' 1 1 

Is  it  Alert 

00990005 

jne 

tryerror 

No  skip 

01000005 

mvi 

0(rl4) ,c 1 E 1 

Set  error  severity 

01010006 

j 

donesev 

01020005 

tryerror  ds 

Oh 

01030005 

cl  i 

0(rl5) , c 1 2 1 

"Error"  severity? 

01040005 

jne 

trywarn 

No  -  skip 

01050005 

mvi 

0(rl4) ,c 1 E 1 

Set  error 

01060005 

j 

donesev 

01070006 

trywarn  ds 

Oh 

01080005 

cl  i 

0(rl5) ,c'3' 

Is  it  Warning 

01090006 

jne 

seti nfo 

01100005 

mvi 

0(rl4) , C 1 W 1 

Set  Warning 

01110005 

j 

donesev 

01120005 

setinfo  ds 

Oh 

01130005 

mvi 

0(rl4) ,c' 1 1 

Indicate  info 

01140005 

donesev  ds 

Oh 

01150005 

mvi 

l(rl4) ,c‘  1 

Put  in  blank 

01160005 

la 

rl4,2(,rl4) 

Ski  p 

01170005 

01180005 

c 

r3,=f '60' 

More  than  60  chars 

01190005 

jnh 

si nglwto 

No  -  issue  it 

01200005 

1  hi 

r3,60 

Only  first  60  chars 

01210005 

01220005 

*  We  only  need 

to  issue  a 

single  WTO 

01230005 

01240005 

singlwto  ds 

Oh 

01250005 

la 

r4,msgtxt+2 

Get  start  of  text 

01260005 

lr 

rl5,rl4 

Get  where  we  stopped 

01270005 

sr 

rl5,r4 

Get  how  much  we've  done 

01280005 

ar 

rl5,r3 

add  length  of  text 

01290005 

stem 

rl5 ,  b 1 0011 ' 

.msgtxt  Set  the  length 

01300005 

betr 

r3,0 

subtract  1 

01310005 

1 

rl5,msgtxta 

Get  source  address 

01320005 

ex 

r3,mvcins 

Move  it 

01330005 

01340000 

mvc 

wtoe.wtol 

init  the  execute  form 

01350007 

la 

r3,msgtxt 

01360005 

sir 

rO,rO 

01370000 

wto 

text=(r3) ,mf=(E,wtoe) 

01380005 

j 

exi  t 

exi  t 

01390000 

01400000 

02250000 

exit  ds 

Oh 

02260000 

lr 

rl ,  rl3 

02270000 

1 

r2,4(r!3) 

02280002 

storage  RELEASE, length=workl ,addr=(rl) 

02290003 
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lr 

rl3,r2 

02300002 

drop 

rl3 

02310000 

02320000 

bagi  t 

ds 

Oh 

02330000 

lm 

14, 12, 12(rl3) 

02340001 

br 

rl4 

02350000 

psi  ze 

equ 

((*-ARSLOG+99)/100)*5 

02360000 

dc 

C1 PATCH  AREA  -  ARSLOG  &sysdate' 

02370000 

pspace 

dc 

25s (*) 

02380000 

org 

pspace 

02390000 

dc 

( (psize+1) /2) s (*) 

02400000 

02410000 

02420000 

mvci ns 

mvc 

0(0, rl4) ,0(rl5) 

02430000 

02450000 

wtol 

wto 

text=, 

+02460000 

desc=(6) , 

+02470000 

mcsflag=(BUSYEXIT) , 

+02480000 

routcde=(ll) , 

+02490000 

mf^L 

02500000 

wtoll 

equ 

*-wtol 

02510000 

1  torg 

02520005 

02530005 

workarea 

dsect 

02870000 

rsa 

ds 

18f 

02880000 

wtoe 

ds 

cl (wtoll ) 

02890006 

msgtxt 

ds 

cl (72) 

02900005 

work! 

equ 

*-workarea 

02910000 

02920000 

pi  i  st 

dsect 

02930000 

i nstance 

ds 

a 

02940005 

tstamp 

ds 

a 

02950005 

logrec 

ds 

a 

02960005 

userid 

ds 

a 

02970005 

acct 

ds 

a 

02980005 

sev 

ds 

a 

02990005 

msgrum 

ds 

a 

03000005 

msgtxta 

ds 

a 

03010005 

03020005 

yregs 

» 

03030007 

i ezwpl 

03040005 

end 

J 

03050005 
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Once  the  exit  routine  is  assembled  and  link-edited  to  a  library,  it  has  to  be 

associated  with  the  exit.  This  can  be  done  in  two  ways: 

►  Use  the  exit  statement  in  PROGXX  parmlib  member.  Refer  to  z/OS  MVS 
Initialization  and  Tuning  Reference,  SA22-7592  for  more  information  about 
the  PROGXX  parmlib  member. 

►  Use  the  SETPROG  EXIT  operator  command.  Refer  to  z/OS  MVS  System 
Commands,  SA22-7627  for  more  information  about  the  SETPORG  EXIT 
command. 

The  following  command  is  used  to  activate  the  exit  routine. 

SETPROG  EXIT .ADD , EXITNAME=ARSLOG , MODENAME=ARSLOG ,  DSN=TEAM5 . LOADLIB 

The  exit  was  link-edited  to  a  normal  library  which  is  not  AFP  authorized. 


10.4  Print  exit  for  Multiplatforms 

There  are  two  ways  to  print  a  document  stored  in  OnDemand:  local  printing  via 
a  LAN  attached  PC  printer,  or  server  printing  via  a  printer  managed  by  the  print 
manager  installed  on  the  OnDemand  server  machine.  The  print  exit  for 
Multiplatforms  can  only  be  used  for  documents  that  are  printed  via  a  server 
printer. 

The  print  exit  for  Multiplatforms  is  supplied  in  arsprt  file  which  resides  in  the  bin 
directory  of  the  OnDemand  install  root  for  each  respective  platform.  If  the  arsprt 
file  is  opened  in  a  text  editor,  you  will  notice  that  it  contains  comments  which 
provide  a  brief  description  of  the  exit  and  the  order  of  the  parameters  which 
OnDemand  hands  to  this  exit. 

Example  10-9  is  an  example  of  an  arsprt  file  which  updates  application  group 
indexes  for  a  certain  document  type  each  time  it  is  sent  to  a  server  printer.  This  is 
a  real  example  from  a  customer  where  the  requirement  was  for  OnDemand  to 
keep  a  record  of  when  a  document  is  re-printed.  The  way  in  which  this  was 
achieved  was  by  using  the  print  exit  to  update  the  indexes  of  a  document  in  order 
to  show  the  last  time  the  document  was  re-printed  and  also  a  counter  which  is 
incremented  to  log  how  many  times  the  document  has  been  re-printed.  There  are 
comments  inserted  into  the  sample  script  in  Example  10-9  which  explain  what 
each  part  of  the  script  is  doing,  but  the  customer  name  and  the  IP  addresses 
have  been  either  altered  or  removed  for  reasons  of  confidentiality. 
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Example  10-9  Sample  print  exit 

#!/bin/ksh 

# 

#  arsprt  -  OnDemand  User  Exit  Printing  Facility 

# 

#  5622-662  (C)  COPYRIGHT  IBM  CORPORATION  1995 

#  All  Rights  Reserved 

#  Licensed  Materials  -  Property  of  IBM 

# 

#  US  Government  Users  Restricted  Rights  -  Use,  duplication  or 

#  disclosure  restricted  by  GSA  ADP  Schedule  Contract  with  IBM  Corp. 

# 

#  This  program  sample  is  provided  on  an  as-is  basis. 

#  The  licensee  of  the  OnDemand  product  is  free  to  copy,  revise, 

#  modify,  and  make  derivative  works  of  this  program  sample 

#  as  they  see  fit. 

# 

#  Function  added  to  update  a  document  each 


#  time  a  reprint  is  done.  Index  'reprint'  is  updated  with  a  'I'  HRl-a 

#  and  index  'log'  is  updated  with  a  date  and  a  counter  of  001  (if  the  HRl-a 

#  document  has  already  been  reprinted,  the  counter  is  added  up  by  001.  HRl-a 

#  Author  =  Hans  Ryden  2000-03-09  HRl-a 

#  (flag  -a  means  added,  flag  -c  means  changed  statement)  HRl-a 


set  -a 
set  -u 
set  -m 
# set  -x 

########################### 

#  3  stmt's  added  by  # 

#  Hasse  Ryden  # 

#  for  debugging  # 

########################### 

#RANDOM=$$ 

#set  -x 

#exec  2>  /usr/lpp/ars/bin/hasse.log.$RANDOM 

RM=/bin/rm 
SED=/bi n/sed 

0S=$ (uname) 

if  [[  ${0S}  =  AIX  ]]  ;  then 
BASE_D IR=/usr/l pp/ars/bi n 

elif  [[  (${0S)  =  HP-UX)  ||  (${0S)  =  SunOS)  ]]  ;  then 
BASE_DIR=/opt/ondemand/bi n 
ARSPRT  H0STNAME= 
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el  se 

print  "Carnot  determine  operating  system" 
exit  1 
fi 


# 

#  $1  -  Printer  Queue  Name 

#  $2  -  Copies 

#  $3  -  Userid 

#  $4  -  Application  Group  Name 

#  $5  -  Application  Name 

#  $6  -  Application  Print  Options 

#  $7  -  Filename  to  Print 


# 

#  NOTE:  It  is  up  to  this  script  to  make  sure  the  file  is  deleted. 

#  example(  -r  option  on  /bin/enq  ) 


FI LE=$7 

0PTS_FI LE=$ {FILE} .opts 
NOTES_FILE=${ FI LE } .notes 
if  [[  -f  $ { 0PTS_F I LE }  ]]  ;  then 
DE  L=  1 

PRT_0PTI0NS=" -o  PASSTHRU=fax_f i 1 e-${FILE}-" 

# 

#  Since  I  am  faxing,  make  sure  that  messages  are  not  produced. 

#  If  debugging  is  needed,  then  this  parameter  should  be  blank. 

# 

#EXTRA_OPTIONS="-o  MSGCOUNT=0" 

EXTRA_OPTIONS="-o  MSGCOUNT=0" 
el  se 
DEL=0 

PRT_OPTIONS= 

EXTRA_OPTIONS= 

fi 

TITLE=$ (pri nt  "$3  $4  $5"  |  ${SED}  ' s/-/  /g  1 ) 
if  [[  ${0S}  =  AIX  ]]  ;  then 

/bin/enq  -r  -P  "$1"  -N  $2  -T  " ${TITLE} "  $6  $ { EXTRA_OPTIONS }  $ { PRT_OPT IONS }  $ { FI LE} 
el  se 

${BASE_DIR}/1  prafp  -p  "$1"  -s  "${ARSPRT_HOSTNAME}"  -o  "C0PIES=${2} "  -o  "  JOBNAME=$ { T I TLE } 11 
-o  "TITLE=${TITLE} "  $6  $ { EXTRACTIONS}  $ { PRT_OPTIONS }  ${ FILE} 
fi 


RC=$? 

if  [[  $ { RC }  =  0  ]]  ;  then 

if  [[  ${0S}  ! =  AIX  ]]  ;  then 
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$ { RM }  -f  ${ FILE} 


el  se 

#################################### 

#  Test  if  filename  ends  up  with  .0  # 

#  If  not, skip  around  code  to  update# 

#  index.  This  prevents  to  update  # 

#  same  index  several  times  as  only  # 


#  one  .cntl  file  is  created  even  # 

#  when  server  print  is  made  for  # 

#  multiple  documents  and  this  # 

#  script  is  called  one  time  for  # 

#  each  doc  to  print.  # 


#################################### 

ext=$7 

ext=${ext##*. } 
if  [[  ${ext}  =  0  ]]  ;  then 
#################################### 

#  Compute  .cntl  filname  from  # 

#  supplied  parameter  $7  # 

#################################### 
f i 1 =$7 

mi ne=$ { f i 1%.*} .cntl 
#################################### 

#  Double  check  if  .cntl  file  exist  # 
#################################### 
if  test  !  -f  $mine 

then  echo  "File  $mine  not  found" 
exit  1 
fi 


#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 


####################################  #  HRl-a  # 

#  Set  static  variables  #  #  HRl-a  # 

####################################  #  HRl-a  # 

host=9.99.99.99  #  HRl-a  # 

nohit=no  #  HRl-a  # 


appl grpl=ICAl og  #  HRl-a  # 

fol derl=ICAl og  #  HRl-a  # 


appl grp2=appl g2  #  HRl-a  # 

fol der2=fol der2  #  HRl-a  # 


appl grp3=appl g3  #  HRl-a  # 
fol der3=fol der3  #  HRl-a  # 
####################################  #  HRl-a  # 
#  Read  info  from  .cntl  file  #  #  HRl-a  # 
####################################  #  HRl-a  # 
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cat  $mine  |grep  -v  APPLICATION | whi 1 e  read  al 
do 

#################################### 

#  Get  the  application  group  name  # 
#################################### 
appl grp=$a2 

appl grp=$ { appl grp##*= } 
#################################### 

#  Set  the  folder  name  depending  on  # 

#  what  the  application  group  name  # 

#  is  # 

#################################### 
if  [[  $  { appl  grp}  =  ${applgrpl}  ]] 

then 

fol der=$fol derl 
else 

if  [[  ${appl grp}  =  ${applgrp2}  ]] 
then 

fol  der=$fol  der2 
el  se 

if  [[  $ { appl grp}  =  ${applgrp3}  ]] 
then 

fol der=$fol der3 

#################################### 

#  Not  an  application  group  we  are  # 

#  looking  for.  Set  nohits=yes  to  # 

#  skip  to  remove  the  .cntl  file  # 
#################################### 

else 

nohi t=yes 
fi 
fi 
fi 

#################################### 

#  If  nohit=no,  get  Account-number  and# 

#  log  info  # 

#################################### 
if  [[  ${nohit}  =  no  ]] 

then 

#################################### 

#  Get  Account  Number  # 


a2  a3  a4  a5  a6  a7  a8  a9  #  HRl-a 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 


#################################### 

account-number=$a4 

account-number=${account-number##*=} 

#################################### 

#  Get  log  info.  If  first  time,  # 

#  then  set  count=001  and  current  # 

#  date  # 

#################################### 


#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 
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log=$a8 
log=${log##*=} 
if  [[  $1  og  =  1111  ]] 
then 
1 og=001 

#################################### 

#  If  not  first  time  for  reprint,  # 

#  then  add  op  old  count  by  1  # 

#################################### 

el  se 

let  1 og=$l og+001 
typeset  -Z3  log 
fi 

#################################### 

#  Set  date  after  log  count  # 

#################################### 

datum='date  +%Y-%m-%d' 
bl ank="  " 

#################################### 

#  Update  this  document  with  count  # 

#  of  reprints  and  current  date  # 
#################################### 
arsdoc  update  -h  $host  -g  $applgrp  -f 

-u  admin  -p  ondemand  -i  "where  account-number= 
fi 

#################################### 


#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 

$folder  -n  log="$log$blank$datum"  -n  reprint=I 
Jaccount-number1 11  -v  #  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 


#  Done,  remove  the  .cntl  file  #  #  HRl-a  # 

####################################  #  HRl-a  # 


done 

rm  $mine 
fi 


#  HRl-a  # 

#  HRl-a  # 

#  HRl-a  # 


fi 

el  se 

( 

if  [[  ${0S}  =  AIX  ]]  ;  then 

echo  /bin/enq  -r  -P  "$1"  -N  $2  -T  "${TITLE}"  $6  ${EXTRA_OPTIONS}  $ { PRT_0PTI0NS } 

${ FILE} 

el  se 

echo  $ { BAS E_D I R } / 1 prafp  -p  "$1"  -s  "${ARSPRT_HOSTNAME} "  -o  “COP I ES=$ { 2 } “  -o 
"J0BNAME=$ {TITLE} "  -o  "T I T LE=$ { T I TLE } "  $6  $ { EXTRA_0PTI0NS }  $ { P RT_OPT I ONS }  ${ FILE} 
fi 

echo  “$ (date) -->0nDemand  Failed  Print  File  >$ { FI LE } <  to  Queue  >$1<" 

)  >/dev/consol e 
exit  $ { RC } 
fi 
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#  If  there  is  an  options  file,  wait  until  the  file  has  been 

#  printed  before  removing  it. 

# 

if  [[  $ { DE L }  ! =  0  ] ]  ;  then 
whi 1 e(  (  1  )) 
do 

if  [[  -f  "$ { FI LE} "  ]]  ;  then 
sleep  30 
el  se 

$ { RM }  -f  $ { 0PTS_F I LE }  $ { N0TES_FI LE } 
break 
fi 
done 

fi 

exit  0 


10.5  Security  exit 

The  OnDemand  security  exit  is  provided  for  all  platforms. 

By  default,  iSeries  activate  the  security  exit  and  use  OS/400  security.  If  the 
security  exit  is  not  enabled,  then  the  OnDemand  user  ID  and  password  have  no 
relation  to  the  OS/400  userid  and  password  and  all  the  OnDemand  System 
Parameter  settings  are  honored.  Enabling  or  disabling  of  this  exit  can  be  done  at 
an  individual  instance  level. 

In  the  following  section,  we  cover  security  exit  for  z/OS. 


10.5.1  Security  exit  on  z/OS 

On  a  z/OS  server,  nothing  goes  without  operating  security  which  is  usually 
provided  by  Security  Access  Facility  (SAF)  of  the  operation  system.  The  security 
exit  is  not  needed  if  you  want  to  run  your  OnDemand  Server  with  the  internal 
OnDemand  security  only.  The  security  exit  is  implemented  to  allow  the 
communication  with  an  external  security  manager  such  as  RACF.  The 
OnDemand  security  system  interface  exit  allows  an  installation  to  control  the 
following  events  or  activities: 

►  Logon. 

►  Change  password. 

►  Add  user  ID  or  delete  user  ID  by  using  the  OnDemand  administrative 
functions. 

►  Obtain  access  to  an  OnDemand  folder. 
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►  Obtain  access  to  an  OnDemand  application  group. 

If  any  of  the  events  or  activities  occur,  a  user  written  exit  routine  can  interact  with 
a  security  system  such  as  RACF  to  determine  if  the  given  activity  is  allowed  or 
not  allowed. 

Also,  the  return  code  option,  ARCCSXIT_SECURITY_OKAY_BUT_VALIDATE_IN_OD, 
allows  a  user  to  perform  some  action  on  a  request  and  then  allows  OnDemand  to 
perform  the  standard  security  processing.  An  example  of  this  would  be  to  not 
allow  a  “new”  password  to  match  the  “old”  password  in  a  change-password 
request;  the  password  must  be  changed. 

The  modules  or  executables  that  are  shipped  with  OnDemand  are  listed  in 
Table  10-1. 


Table  10-1  Security  exit  modules 


Module 

Description 

ARSUPERM 

This  c-module  provides  the  interface  between  the  OnDemand 

System  and  the  ARSUSECX  Module 

ARSUSEC 

This  c-module  provides  the  interface  between  the  OnDemand 

System  and  the  ARSUSECX  Module 

ARSUSECA 

Mapping  of  the  data  structure  presented  to  the  exit  routine  associated 
with  the  exit  point  defined  by  ARSUSEC  in  Assembler 

ARSUSECH 

Mapping  of  the  data  structure  presented  to  the  exit  routine  associated 
with  the  exit  point  defined  by  ARSUSEC  in  C 

ARSUSECJ 

Sample  JCL  Stream  for  assemble  and  bind  ARSUSECX  and 
ARSUSECZ 

ARSUSECX 

the  interface  module  for  the  MVS  Dynamic  Exit  Facility 

ARSUSECZ 

The  Security  Exit  Module  Sample 

Note:  The  security  exit  is  an  enhancement  which  is  not  shipped  with  the  basic 
code.  It  is  available  with  PTF  UQ58458  UQ59190. 


All  Modules  are  found  in  the  SARSINST  library  after  applying  the  PTF.  The 
sequence  of  this  exit  using  the  MVS  Dynamic  Exit  Facility  is  different  from  the 
classical  interface  with  exit  modules  or  security  exit  in  an  CICS  environment.  The 
kernel  code  was  updated  to  allow  external  security.  The  OnDemand  Kernel  code 
calls  a  DLL  as  an  interface  to  the  exit.  Modules  ARSUSEC  and  ARSUPERM, 
provided  as  C  source  code  modules  and  as  executables,  fulfill  this  function. 
There  is  no  need  to  change  them  and  to  re-compile. 
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The  source  is  delivered  mainly  for  understanding  the  entire  security  system  exit. 
If  you  want  to  change  them,  they  have  to  be  re-compiled  and  bound  as  a  C  DLL. 
These  modules  communicate  with  the  ARSUSECX  module  which  is  an  interface 
to  the  MVS  Dynamic  Exit  Facility.  The  security  exit  module  ARSUSECZ  is  the 
delivered  sample  with  the  PTF.  It  shows  how  to  perform  the  security  checks  with 
a  Security  Exit  Facility  (SAF)  interface.  RACF  is  a  program  that  uses  SAF.  The 
ARSUSECFI  is  a  C  source  code  module  which  passes  the  data  structure  as  an 
input  for  every  exit  (ARSUSECZ)  which  is  provided.  The  ARSUSEA  provides  the 
same  in  assembler  language. 


Note:  You  can  have  more  than  one  Security  exit  defined  to  the  MVS  Dynamic 
Exit  Facility.  For  example,  define  a  different  security  exit  for  each  instance. 


Tip:  The  only  module  which  you  have  to  change  is  the  provided  source  code 
ARSUSECZ  to  meet  you  requirements.  This  has  to  be  assembled  and  linked 
into  a  library  which  is  accessible  for  the  MVS  Dynamic  Exit  Facility. 


Security  systems  other  than  SAF 

The  sample  provided  by  IBM  is  a  SAF  sample.  However,  there  are  installations 
using  their  own  security  system  or  use  it  as  an  enhancement  together  with  SAF 
environment.  These  systems  can  be  accessed  if  they  provide  a  proper  assembler 
callable  interface.  The  security  exit  sample  code  contain  an  example  for  every 
function.  These  functions  can  be  changed  or  updated  in  the  sample  code. 

For  example,  if  your  folder  permissions  are  stored  in  an  external  security  system 
without  any  SAF  interface,  this  part  has  to  be  updated  to  call  this  external 
security  system.  For  demonstration  purposes,  the  access  to  an  application  group 
code  sample  is  shown  here  in  Example  10-10.  This  sample  issues  the 
RACROUTE  macro.  If  a  different  external  security  manager  is  used,  this  code 
has  to  be  updated  for  a  proper  call  of  this  system. 

Example  10-10  Sample  for  an  application  group  request 

TITLE  1 HACAPGP :  Process  an  Application  Group  Access  Request' 

****  HACAPGP:  Process  an  Application  Group  Access  Request 


*  Function: 

*  This  procedure  processes  a  request  for  Read  access  to  an 

*  OnDemand  Application  Group. 

* 


*  Inputs: 

*  Registers: 
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RIO:  Points  to  the  WORKMAP  structure. 
Rll:  Points  to  the  ARSUSECA  structure. 


* 

*  Outputs  (normal ) : 

*  Registers: 

*  RO:  Unchanged. 

*  Rl:  Unchanged. 

* 


R15:  Contains  one  of  the  following  return 
code  values  (see  the  ARSUSECA  DSECT 
for  return  code  details): 


ARSUSECA_RCNORM 
ARSUSECA  RCPERMS 


* 


*  Outputs  (error) : 

*  None. 

* 

* 

*  Exits  (normal): 

*  Via  Program  Return  (PR) 

* 


* 

*  Exits  (error) : 

*  None. 

* 

* 


*  Linkage: 

*  Via  the  ICALL  macro  interface. 

* 


* 


*  Special  Considerations: 

*  None. 

* 


* 


*  Algorithm: 

*  .  The  requesting  User  ID  and  the  target  Application  Group 

*  Name  strings  are  copied  to  the  local  work  area. 

* 

*  Note  that: 

*  .  These  strings  will  be  truncated  if  they  are  longer 

*  than  the  maximum  length  as  defined  by  the  ARSUSECA 

*  DSECT. 

* 

*  .  It  is  expected  that  the  SAF  conforming  security 

*  system  will  enforce  the  length  and  character  set 

*  restrictions  associated  with  User  ID  and  resource 
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profile  name  strings. 


A  RACROUTE  AUTH  request  is  issued  to  determine  if  the 
requesting  User  ID  is  to  be  granted  Read  access  to  the 
Appl ication  Group. 

The  procedure  return  code  is  set  to  ARSUSECA_RCNORM  for 
the  following  situations: 

-  The  SAF  conforming  security  system  has  granted 
access. 

-  The  SAF  conforming  security  system  has  not  made  a 
decision.  This  can  occur,  for  example,  when  the 
Resource  Class  is  not  defined  to  the  security 
system  or  when  no  profile  exists  for  the  named 
enti ty . 

Otherwise,  the  procedure  return  code  is  set  to 
ARSUSECA  RCPERMS. 


Exi  t 


SPACE  2 

HACAPGP  DC  OH 1  0 1 
PUSH  USING 
EJECT  , 


Copy  the  requesitng  User  ID  string,  blank  padding  or  truncating 
as  required. 


SPACE  2 

L  R14, ARSUSECA  CURUIDP 


Fetch  the  ptr  to  the 
ID  string  of  the  user 
being  updated. 


R15, ARSUSECA  CURUIDL 


Fetch  the  User  ID  string 
1 ength . 


LA  RO.WKUIDS 

LA  R1 , L 1 WKUIDS ( , 0) 


Set  the  MVCL  'To'  adrs. 
Set  the  MVCL  'To'  len. 


STC  R15.WKUIDL 


Set  the  User  ID  length 
field  as  required  by 
RACROUTE. 
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CLR 

R15.R1 

Is  the  User  ID  string 

* 

too  long  to  be  contained 

* 

* 

in  the  copy  area  -- 

BNH 

HAAG200 

Br  if  not 

* 

STC 

Rl.WKUIDL 

Else  truncate  the  string. 

HAAG200 

DC 

OH  1  0  1 

* 

ICM 

R15 ,  B 1 1000 1 .BLANKS 

Set  the  MVCL  pad  value. 

MVCL 

R0.R14 

Copy  the  User  ID  string 

* 

EJECT 

J 

to  the  local  work  area. 

* 

* 

*  Copy  the  Application  Group  name  (i.e.,  the  name  of  the  entity 

*  to  which  access  is  being  requested),  blank  padding  or 

*  truncating  as  required. 

* 

*  The  actual  entity  name  string  (i.e.,  exclusive  of  the  trailing 

*  blanks)  is  translated  to  convert  any  embedded  blanks  or  invalid 

*  characters  to  the  character  value  defined  by  the  RPN I N V  equate. 

*  In  addition,  lower  case  characters  *MAY*  be  converted  to  upper 

*  case. 

* 

*  _ _ 


SPACE  2 

L  R14, ARSUSECA_AGNMP 

L  R15, ARSUSECA_AGNML 

LA  RO.WKENTNM 
LA  R1,L'WKENTNM(,0) 

ICM  R15 , B ' 1000 1 .BLANKS 

MVCL  R0.R14 

L  R15, ARSUSECA_AGNML 

LA  R14, L 1 WKENTNM( , 0) 


Fetch  the  ptr  to  the 
Application  Group  name. 

Fetch  the  Application 
Group  name  length. 

Set  the  MVCL  'To'  adrs. 

Set  the  MVCL  'To'  len. 

Set  the  MVCL  pad  value. 

Copy  the  Application  Group 
name  to  the  local  work 
area. 

Fetch  the  Application 
Group  name  length. 

Load  the  length  of  the 
entity  name  buffer  area. 


258  Content  Manager  OnDemand  Guide 


CLR 

R15.R14 

•k 

Br  if  the  name  string 

* 

BNH 

HAAG400 

•k 

was  not  truncated. 

LR 

R15.R14 

Else  use  the  truncated 

HAAG400 

DC 

OH  1  0  1 

BCTR 

R15,0 

•k 

Convert  the  string  to 

* 

EX 

R15.TRENTNM 

•k 

valid  characters. 

SLL 

R14, 16 

•k 

Set  the  entity  buffer 

ST 

R14.WKENTBFL 

•k 

length  fields. 

* 

EJECT 

J 

* 

*  Issue  a  RACROUTE  AUTH  request  to  determine  if  the  user  has  Read 

*  access  to  the  Application  Group. 

* 

* 

SPACE  2 

MVI  WKSAFCLL, L 1 WKSAFCLN  *  Build  the  SAF  Resource 

MVC  WKSAFCLN, ARSAGRN  *  Class  Name  area. 

* 

MVC  WKRACFPL(LNRACAUT) ,SKRACAUT 

*  Build  a  RACROUTE  AUTH 

*  template  pi ist. 

* 

XR  R15.R15  *  Zero  the  ACEE  pointer 

ST  R15.WKACEEP  *  return  area. 

SPACE  2 


RACROUTE  REQUEST=AUTH,  Validate  access  authority  + 

CLASS=WKSAFCLS,  SAF  Resource  Class  area  + 

ATTR=READ,  Authority  requested  + 

ENTITYX=(WKENTBUF,NONE) ,  Resource  Profile  Name  area  + 

USERID=WKUIDS,  User  ID  to  validate  + 

WORKA=WKRACWKA,  SAF  work  area  + 

RELEASE=2608,  OS/390  2.8  level  + 

MSGRTRN=NO,  Do  not  return  messages  + 


MF=(E,WKRACFPL) 

EJECT  , 

* 

* 

*  The  RACROUTE  operation  is  considered  successful  if  the 

*  validation  was  completely  successful  or  the  security  system 

*  made  no  decision. 

* 

* 

SPACE  2 

LA  R14.WKRACFPL  Set  the  ptr  to  the 

*  RACROUTE  interface 

*  plist. 
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USING  SAFP.R14 


* 


* 

* 

* 

LA 

R2 , ARSUSECA_RCNORM( , 0) 

Assume  the  RACROUTE 
operation  completed 
successful ly. 

LTR 

R15.R15 

Is  this  the  case  -- 

* 

BZ 

HAAG  FIN 

Br  if  so. 

* 

* 

CL 

R15.SAFRN0D 

Was  no  decision  made  by 
the  security  system  -- 

* 

BE 

HAAG  FIN 

Br  if  so. 

* 

* 

* 

* 

LA 

R2 , ARSUSECA_RCPERMS( , 0) 

Else  indicate  the  user 
is  not  to  be  granted 
access  to  the  Applicatii 
Group. 

DROP 

EJECT 

R14 

J 

SAFP  (ICHSAFP)  base 

* 

*  Delete  the  newly  created  ACEE  (if  it  exists)  and  exit. 

* 

*  At  entry  to  this  code  segment  it  is  expected  that  GPRs  are 

*  loaded  as  follows: 

* 

*  R2:  Contains  the  procedure  return  code  value. 

* 

* 

SPACE 

2 

HAAG  FIN 

DC 

OH  1  0 1 

L 

Rl.WKACEEP 

Fetch  the  potential  ptr 

* 

to  the  newly  constructed 

* 

ACEE. 

SPACE 

2 

ICALL 

DELACEE 

Delete  the  new  ACEE. 

SPACE 

2 

HAAGXIT 

DC 

OH 'O' 

LR 

R15.R2 

Set  the  procedure 

* 

return  code. 

EREG 

R0.R1 

Restore  the  entry  regs 

PR 

» 

And  exit 

POP 

USING 
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OnDemand  SAF  resource  classes 

You  have  to  define  SAF  resource  classes  ARS1FLDR  and  ARS1APGP  for 
folders  and  application  group.  Refer  to  Appendix  E,  in  IBM  Content  Manager 
OnDemand  forz/OS  and  OS/390  -  Configuration  Guide,  GC27-1373  for  more 
information  about  the  resource  classes. 


Important:  Even  if  the  security  exit  can  check  the  UID  and  password  against 
SAF  or  other  security  systems,  every  user  has  to  be  defined  in  OnDemand  in 
every  instance.  The  ARSADM  program  can  be  used  to  create  users  in  batch 
mode,  as  a  command  from  the  USS  command  line  and  using  a  file  as  input. 


Activate  the  security  exit 

The  enablement  or  disablement  of  the  security  exit  is  controlled  by  settings  in  the 
ARS.INI  file,  which  resides  in  the  usr/lpp/ars/config  directory. 

To  enable  the  exit  for  the  following  events: 

►  Logon 

►  Changing  password 

►  Adding  or  deleting  a  user  ID  via  the  OnDemand  administrator  interface 

The  following  statement  must  be  added  to  the  ARS.INI  file: 
SRVR_FLAGS_SECURITY_EXIT=1 

To  enable  the  exit  for  the  following  events: 

►  Accessing  an  OnDemand  folder 

►  Accessing  an  OnDemand  application  group 

The  following  statement  must  be  added  to  the  ARS.  INI  file 
SRVR_FLAGS_F0LDER_EXIT=1 

For  disablement,  set  the  values  to  0. 

Activate  the  security  exit  in  a  z/OS  environment 

The  module  ARSUSECX  interfaces  with  the  MVS  Dynamic  Exit  Facility  to 

►  Define  the  logical  exit  point  name,  ARS.SECURITY. 

►  Route  the  control  to  a  set  of  associated  exit  routines  and  process  the  results 
of  their  execution. 


Note:  The  sample  is  designed  to  process  the  feedback  of  the  exit  one  at  a 
time,  even  if  you  are  running  more  than  one  exit. 
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An  exit  routine  must  be  eligible  for  execution  which  is  done  by  associating  a 
logical  exit  point  (ARS. SECURITY).  In  this  example,  the  MVS  Dynamic  Exit 
Facility  provides  several  methods  performing  this  association.  You  can  use  the 
PROGXX  statement  in  Sysl.Parmlib  to  define  exits  to  the  Dynamic  Exit  Facility 
at  IPL  time  (Example  10-11). 

Example  10-11  Exit  statement  for  PROGXX 

EXIT  ADD  EXITNAME(ARS. SECURITY)  MODNAME(ARSUSECZ) 


Also,  the  following  operator  commands  can  be  used  to  add  the  exit: 

SETPROG  EXIT, ADD, EXITNAME=ARS. SECURITY, MODENAME=ARSUSECZ 


Important:  The  load  module  must  be  found  in  LPA  or  a  LNLKLST  data  set. 


The  security  exit  can  only  handle  the  functions  described  earlier.  If  you  want  to 
restrict  access  to  folder  and  application  groups  based  on  index  values,  this  can 
be  done  with  the  internal  OnDemand  security.  The  restriction  for  an  application 
group  is  maintained  by  RACE  Once  a  user  has  access  to  the  application  group, 
there  is  no  way  of  limiting  the  access  to  this  application  group  with  any  external 
security.  In  order  to  limit  access  to  specific  application  group  data,  enter  a  Query 
Restriction  to  the  Application  Group  to  create  an  SQL  “where  clause”. 

Figure  10-3  shows  a  query  that  is  restricted  to  statements  with  balance 
exceeding  200.  This  query  restriction  is  for  all  user  of  the  system  (‘PUBLIC)  that 
do  not  have  a  separate  query  restriction. 
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Figure  10-3  Query  restriction  set 

ARSYSPIN  and  sample  APKACIF  exit  on  z/OS 

This  additional  facility  is  provided  by  an  PTF  PQ57769.  The  documentation  is 
found  on  the  Web  site  to  download.  The  documentation  is  provided  as  a  PDF  file 
and  the  arsodpub  member  in  sarsinst  member  is  pointing  to  the  following  Web 
site: 

http: //www. i bm. com\software\data\ondemand\390\l i brary.html 

The  file  to  download  is  arsyspi  n .  pdf.  You  can  search  for  this  file  and  it  will  be  link 
to  the  following  Web  site: 

http: //www-1 .i bm.com/support/docvi ew.wss?ui d=swg2 7002351 

Download  the  arsyspin.zip  file  and  you  will  get  the  documentation  and  samples 
on  how  to  start  and  create  application  group,  application  and  folders.  These 
samples  can  be  used  with  minimum  changes  as  a  template.  The  Web  site  also 
shows  how  to  unzip  this  file. 
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The  JES  Spool  Capture  facility  (ARSYSPIN)  provides  a  means  to  collect  and 
consolidate  JES  Spool  (SYSOUT)  data  set  into  one  or  more  files  so  they  can  be 
archived  by  OnDemand.  The  facility  executes  as  a  started  task  in  its  own  address 
space.  A  control  statement  file  is  used  to  provide  ARSYSPIN  parameters.  These 
parameters  specify  JES  Spool  file  selection  criteria  (for  example  the  sysout  class 
taken  for  capture  output)  and  other  operational  characteristics.  ARSYSPIN  creates 
an  intermediate  output  file  which  contains  one  or  more  spool  files  from  one  or 
more  jobs.  The  intermediate  output  file  is  indexed  and  stored  in  OnDemand  using 
the  ARSLOAD  program.  ARSYSPIN  invokes  ARSLOAD  when  sufficient  data  has  been 
captured  in  the  intermediate  output  file.  ARSLOAD  calls  the  indexer  program 
(APKACIF)  to  extract  the  index  values  from  the  data  and  store  them  in  an  index  file. 
ARSLOAD  adds  these  index  values  to  the  database  and  stores  the  data  object. 

Special  Considerations  for  APKACIF  exits  written  in  COBOL 

The  provided  sample  exit  is  written  as  a  COBOL  main  program.  In  order  to 
prevent  the  language  environment  from  creating  and  destroying  the  COBOL 
runtime  environment,  each  time  the  ARSSPVIN  is  called,  a  CEEUOPT  CSECT 
must  be  assembled  and  link-edited  with  the  COBOL  object  code.  The  sample 
taken  from  CEE.SCEESAMP  must  be  updated  and  the  following  option  must  be 
specified: 


Important:  RTEREUS=(ON) 


In  addition,  you  must  be  sure  that  the  resulting  module  is  link-edited  as  NOT 
RE-ENTRANT  and  NOT  REUSEABLE.  This  is  required  to  allow  the  local 
variables  within  the  COBOL  exit  code  to  retain  their  values.  This  exit  is  invoked 
several  times  during  an  ACIF  run.  See  Example  10-12,  the  JCL  sample  for 
details.  The  sample  source  code  can  be  found  in  the  SARSINST  library  member 
ARSSPVIN. 


Example  10-12  JCL  sample 


//ALLOC 

EXEC 

//OBJ 

DD 

// 

// 

//* 

//*  . 

— 

//* 

//COBOL 

EXEC 

//  PARM= ( 

// 

//STEPLIB 

DD 

//SYSPRINT 

DD 

//SYSLIB 

DD 

// 

DD 

PGM= I EFBR14 

DSN=&&0BJ , D I S  P= (NEW, PASS) , 

UNIT=VI0, SPACE= (TRK, (30, ,5)) , 

DCB= (LRECL=80 , BLKSIZE=6160, RECFM=FB , DS0RG=P0) 


PGM=IGYCRCTL, REGION=OM, 

'NODYNAM, LIB, LIST, MAP, OBJECT' , 

1  RENT, APOST.TRUNC (BIN) ,N0SEQ, XREF 1 ) 

DISP=SHR,DSN=C0B0L.V2R1M0.SIGYC0MP 

SYS0UT=* 

DISP=SHR,DSN=ARSV7 10. 0DMP7 10. SARSINST 
DISP=SHR, DSN=CEE. SCEESAMP 
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//SYSLIN  DD  DISP= (OLD , PASS) ,  DSN=&&OBJ (ARSSPVIN) 

/ /SYSUT1  DD  UNIT=VIO,SPACE=(460, (3500,100)) 

//SYSUT2  DD  UNIT=VIO,SPACE=(460, (3500,100)) 

//SYSUT3  DD  UNIT=VIO,SPACE=(460, (3500,100)) 

//SYSUT4  DD  UNIT=VI0,SPACE=(460, (3500,100)) 

//SYSUT5  DD  UNIT=VIO,SPACE=(460, (3500,100)) 

//SYSUT6  DD  UNIT=VI0,SPACE=(460, (3500,100)) 

//SYSUT7  DD  UNIT=VIO,SPACE=(900, (7000,100)) 

//SYSIN  DD  DISP=SHR, DSN=ARSV710 .ODMP710 . SARSINST (ARSSPVIN) 

//* 

//*  - - - - - - 

//* 


//ASM  EXEC  PGM=ASMA90 , REGION=OM, 

//  PARM=( 'NOOBJECT, DECK, NOTERM, XREF(SHORT) , LIST (MAX) 1 , 

//  1 ASA.MXREF ( FULL) 1 ) 

//STEPLIB  DD  DISP=SHR,DSN=HLASM.V1R4MO.SASMMOD1 
//  DD  DISP=SHR,DSN=HLASM.V1R4MO.SASMMOD2 

//SYSPRINT  DD  SYSOUT=* 

//SYSTERM  DD  DUMMY 
//SYSADATA  DD  DUMMY 
//SYSLIN  DD  DUMMY 

//SYSPUNCH  DD  DISP= (OLD , PASS) ,DSN=&&OBJ (CEEUOPT) 

//SYSUT1  DD  UNIT=SYSALLDA,SPACE=(CYL, (10)) 

//SYSLIB  DD  DISP=SHR, DSN=CEE. SCEEMAC 
//  DD  DISP=SHR, DSN=CEE. SCEESAMP 

//  DD  DISP=SHR, DSN=SYS1 .MACLIB 

//  DD  DISP=SHR, DSN=SYS1 .MODGEN 

//SYSIN  DD  * 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


ic'k'k'k'k'k'k'k'k'k'k'kick'k'k'k'k'k'k'k'k'k'k'k'k'k'kick'k'k'k'k'k'k'kick'kick'k'k'k'k'k'k'k'k'k'k'k'k'k'kick'k'k'k'k'k'k'kick'k 


*  OS/390  2.9  LANGUAGE  ENVIRONMENT  * 

*  * 

*  LICENSED  MATERIALS  -  PROPERTY  OF  IBM.  * 

*  * 

*  5647-A01  5688-198  * 

*  * 

*  (C)  COPYRIGHT  IBM  CORP.  1991,  2000  * 

*  ALL  RIGHTS  RESERVED  * 

*  * 


*  US  GOVERNMENT  USERS  RESTRICTED  RIGHTS  -  USE,  * 

*  DUPLICATION  OR  DISCLOSURE  RESTRICTED  BY  GSA  ADP  * 

*  SCHEDULE  CONTRACT  WITH  IBM  CORP.  * 

*  * 

*  STATUS  =  HLE6609  * 

*  * 

ic'k'k'k'k'kicic'k'k'k'k'k'k'k'k'k'k'k'kic'k'kic'k'kic'k'k'k'kic'k'k'k'k'kic'k'kick'k'k'kic'k'k'k'k'kic'kicic'kic'k'k'k'k'kic'kic'k'kic 


/ 

/ 

/ 

/ 

/ 

/ 

/ 

/ 

/ 

/ 

/ 

/ 

/ 

/ 

/ 

/ 

/ 

/ 


CEEUOPT  CSECT 
CEEUOPT  AMODE  ANY 
CEEUOPT  RMODE  ANY 
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CEEXOPT  ABPERC= (NONE)  ,  + 

ABTERMENC=(ABEND) ,  + 

AIXBLD= (OFF) ,  + 

ALL31= (OFF) ,  + 

ANYHEAP=(16K,8K, ANYWHERE, FREE),  + 

BEL0WHEAP=(8K,4K, FREE) ,  + 

CBLOPTS=(ON) ,  + 

CBLPSHPOP= (ON) ,  + 

CBLQDA=(OFF) ,  + 

CHECK= (ON) ,  + 

COUNTRY= (US) ,  + 

DEBUG=(OFF) ,  + 

DEPTHCONDLMT=(10) ,  + 

ENVAR=("),  + 

ERRCOUNT= (0) ,  + 

ERRUN I T= ( 6 )  ,  + 

FILEHIST=(ON) ,  + 

HEAP=(32K,32K,ANYWHERE,KEEP,8K,4K) ,  + 

HEAPCHK=(OFF,1,0),  + 

HEAPPOOLS= (OFF, 8, 10, 32, 10, 128, 10, 256, 10, 1024, 10, 2048,  + 

10),  + 

INFOMSGFILTER=(OFF, , , ,) ,  + 

INQPCOPN= (ON) ,  + 

INTERRUPT=(OFF) ,  + 

LIBRARY=(SYSCEE) ,  + 

LIBSTACK=(4K,4K,FREE) ,  + 

MSGFILE=(SYSOUT,FBA, 121,0, NOENQ) ,  + 

MSGQ= (15) ,  + 

NATLANG=(ENU) ,  + 

NOAUTOTASK= ,  + 

NONON I PTSTACK= (4K, 4K, BELOW, KEEP) ,  + 

NOTEST= (ALL,*, PROMPT, INSPPREF),  + 

NOUSRHDLR=(  "  ) ,  + 

OCSTATUS= (ON) ,  + 

PC= (OFF) ,  + 

PLITASKCOUNT= (20) ,  + 

POSIX= (OFF) ,  + 

PROFILE=(OFF,  "),  + 

PRTUN I T= ( 6 )  ,  + 

PUNUN I T= ( 7 ) ,  + 

RDRUNIT=(5) ,  + 

RECPAD= (OFF) ,  + 

RPTOPTS=(OFF) ,  + 

RPTSTG=(OFF) ,  + 

RTEREUS=(ON) ,  <====  ATTENTION  + 

RTLS=(OFF) ,  + 

S I  MV RD= (OFF) ,  + 

STACK=(128K, 128K, BELOW, KEEP)  ,  + 

STORAGE=(NONE, NONE, NONE, 8K) ,  + 
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TERMTHDACT  = (TRACE , ,96) ,  + 
THREADHEAP=(4K,4K, ANYWHERE, KEEP) ,  + 
TRAC E= (OFF, 4K, DUMP , LE=0) ,  + 
TRAP=(ON,SPIE) ,  + 
UPSI=(00000000),  + 
VCTRSAVE= (OFF) ,  + 
VERSIONS"),  + 


XUFLOW= (AUTO) 

END 

/* 

//* 

//*  - - - - 

//* 

// LKED  EXEC  PGM=IEWL, COND= (4, LT, COBOL) , 

//  PARM=('CASE=MIXED,COMPAT=CURR, LIST, LET, MAP, XREF1) 

//SYSPRINT  DD  SYSOUT=* 

//SYSUT1  DD  UNIT=VIO, SPACE= (TRK, (30)) ,DSN=&&LUT1 

//SYSLIB  DD  DISP=SHR,DSN=CEE.SCEELKED 

//OBJECT  DD  DISP=(OLD, DELETE) ,DSN=&&OBJ 

//SYSLMOD  DD  DISP=SHR,DSN=RAICER. SAMPLE. LOADLIB 

//SYSLIN  DD  * 

INCLUDE  OBJECT (ARSSPVIN) 

INCLUDE  OBJECT (CEEUOPT) 

ENTRY  ARSSPVIN 
NAME  ARSSPVIN(R) 

/* 


Enable  the  exit 

To  activate  the  exit,  you  must  add  the  executable  into  a  loadlib  in  Steplib 
(ARSLOAD)  procedure  and  you  must  supply  the  ACIF  control  statement  Inputexit 
=  ARSSPVIN.  This  can  be  done  when  updating  an  application  in  the  indexer 
properties  dialog  box  (Figure  10-4).  When  getting  to  the  Indexer  Information,  you 
can  modify  them  by  typing  in  the  statement  with  a  keyboard  or  using  sample  data 
and  specify  the  exit  in  the  exit  panel. 
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Update  an  Application 
Indexer  Properties 


2<J 

2Si 


Data  Format  |  Resource  Information  |  Output  Information  |  Exit  Information  | 

Carriage  Control 


Data  Conversion  | No 
Line  Count  fi 


File  Format  |  Record 
Length  |l  33 
Font  Information 


CC  |  Yes  ~^~1 

CC  Type  IANS!  [EBCDIC]  -  | 
New  Page  [ 


CHARS 


TRC 

|  No 

3 

Coded  Font  1 

PR  Mode 

1 

Coded  Font  2  | 

Code  Page 

|500 

Coded  Font  3  | 

MCF2 

1 CP/CS 

3 

Coded  Font  4  | 

Maximum  pages  to  display: 
All  Pages  (*  |l  00 


Pages 


OK 


Cancel 


J 


Apply 


Mppiy 


Help 


i  icip 


Figure  10-4  Indexer  properties 


Select  Exit  Information  (Figure  10-5)  and  type  the  name  of  the  exit  in  there. 
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Figure  10-5  Specify  the  exit  load  module  name 

This  will  update  the  indexer  information  as  shown  in  Example  1 0-1 3. 

Example  10-13  Index  information 

FIELD3=0, 105,8, (TRIGGER= 1 , BASE=0) 

FIELD4=-1,77, 13,  (TRIGGERS, BASE=0) 

I NDEX 1 =X 1 998587899695 1 , FIELD1 , (TYPE=GR0UP, BREAK=YES) 

INDEX2=X 1 9985979699A395819485 ’ , FIELD2 , (TYPE=GR0UP, BREAK=YES) 

I NDEX3=X 1 998481A385 1 , FIELD3, (TYPE=GR0UP , BREAK=YES) 

INDEX4=X 1 99858789969595819485 ' , FIELD4, (TYPE=GR0UP, BREAK=YES) 
DCFPAGENAMES=NO 
UNIQUEBNGS=YES 
IMAGE0UT=ASIS 
INDEX0BJ=GR0UP 
INDEXSTARTBY=1 
INSERTIMM=N0 
RESTYPE=N0NE 

INPEXIT=ARSSPVIN  < -  UPDATE  ! 


/*  region  */ 
/*  reportname  */ 
/*  rdate  */ 
/*  regionname  */ 
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Note:  If  you  are  running  OnDemand  on  z/OS,  the  ACIF  indexer  is  running  in  a 
OS/390  environment.  The  normally  provided  Parmfi  1  e  in  JCL  for  ACIF  is  now 
provided  as  the  indexer  information  in  the  application  definition. 
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11 


Did  you  know? 


In  this  chapter  we  offer  various  tidbits  of  information  that  were  gathered  in  the 
course  of  writing  this  book.  Each  section  discusses  a  different  feature  of 
OnDemand  that  may  be  useful  in  administering  a  production  environment. 

This  chapter  includes  the  following  topics: 

►  Document  Audit  Facility 

►  Related  Documents  feature 

►  Store  OnDemand 

►  Batch  OnDemand  commands  in  z/OS 

►  Testing  PDF  indexer  in  z/OS 


©  Copyright  IBM  Corp.  2003.  All  rights  reserved. 
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11.1  Document  Audit  Facility 

OnDemand  has  incorporated  a  feature  called  the  Document  Audit  Facility  or  DAF. 
This  function  allows  for  basic  approval  routing  of  a  document.  An  administrator 
can  define  status  for  a  document,  and  users  with  the  appropriate  permissions 
have  the  ability  to  click  a  button  on  the  client  to  change  the  status  of  the 
document. 

An  example  of  this  feature  is  a  company  that  must  review  each  of  their  billing 
statements  before  they  are  released  to  the  customer.  An  administrator  sets  up  an 
index  to  the  document  that  can  be  one  of  three  values:  Hold,  Pass,  or  Fail. 

When  documents  are  loaded,  they  are  loaded  with  a  default  of  “Hold”  status.  The 
only  users  who  have  permission  to  view  these  “Hold”  documents  are  the  auditors 
or  reviewers.  Once  the  reviewer  has  verified  the  document,  they  can  click  a 
button  to  set  the  document  to  either  “Pass”  or  “Fail”  status. 

This  action  changes  the  value  of  that  index.  Customer  permissions  will  be  set  up 
in  such  a  way  that  they  can  only  view  documents  that  have  “Pass”  status;  there 
may  be  another  group  of  people  who  can  view  documents  with  a  status  of  “Fail” 
status.  Following  is  a  discussion  on  how  to  implement  this  example. 
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11.1.1  Create  a  status  field  in  the  application  group 

Add  a  field  to  the  application  group  that  is  called  audit  or  status.  This  field  must 
be  a  one-character  string  with  the  Case  set  to  upper  and  the  Type  set  to  fixed.  In 
the  Mapping  section  of  the  application  group,  add  database  values  and  displayed 
values  for  each  of  the  required  status.  See  Figure  11-1  for  our  application  group. 
We  have  added  three  statuses,  Hold  (H),  Pass  (P)  or  Fail  (F). 


Figure  11-1  Adding  status  field  to  the  application  group 
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11.1.2  Set  a  default  in  the  application 

Decide  what  you  want  the  default  value  for  this  index  to  be  and  set  this  default  in 
the  application.  For  our  example,  documents  should  be  loaded  to  the  system  with 
“Hold”  status,  so  we  set  the  default  to  H.  See  Figure  11-2  for  our  example. 


Figure  11-2  Setting  default  in  application 
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11.1.3  Update  permissions  for  various  users 

Update  the  permissions  for  your  users  or  user  groups  to  restrict  them  to 
documents  with  specific  status.  In  our  example,  we  have  a  customer  with  the 
user  ID  of  customerl  who  should  only  be  allowed  to  view  statements  once  they 
have  been  audited  -  or  assigned  a  “Pass”  (P)  status.  See  Figure  1 1  -3  for  this 
example. 


Figure  11-3  Query  restriction 

In  our  case  (not  shown  here),  we  set  a  customer  (Summit  Sports),  and  added  a 
restriction  so  that  the  customer  can  only  see  the  invoices  from  the  customer’s 
account,  000-000-006.  We  can  do  this  by  creating  a  query  restriction  for  the  user. 
Query  restrictions  can  also  be  assigned  at  the  user  group  level. 

We  also  have  a  user  called  auditor.  This  is  the  person  who  is  allowed  to  change 
the  status  of  documents.  This  person  has  no  query  restriction  and  must  have 
update  authority  to  the  documents. 
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1 1 .1 .4  Create  folders  for  each  user  type 

In  our  example,  we  created  separate  folders  for  the  customer  view  and  the 
auditors  view  so  that  the  status  field  would  not  be  visible  from  the  customer 
folder.  The  folder  created  for  the  auditor  contained  all  the  fields  including  the 
status  of  each  document. 


Note:  To  reduce  administration,  it  may  be  advantageous  to  have  a  single 
folder,  as  it  is  possible  to  configure  a  folder  to  have  different  field  views  for 
different  users. 


11.1.5  Create  the  Document  Audit  Facility  control  file 

The  Document  Audit  Facility  is  controlled  by  a  file  named  ARSGUI  .CFG,  which  you 
must  create  and  store  in  the  Windows  client  program  directory  (\Program 
Files\IBM\0nDemand32).  The  DAF  file  has  the  same  format  and  syntax  as  a 
standard  Windows  INI  file.  This  file  contains  a  section  named  AUDIT,  which 
identifies  one  or  more  folder  sections.  Each  folder  section  identifies  a  folder  that 
can  be  audited.  See  Figure  11-4  for  our  DAF  control  file. 


[AUDIT] 

FOLDERS=stat ements 
[stat ements] 

FOLDER=customer  statements  -  Auditors 

AUDIT_FIELD=St at US 

PASS_TEXT  =  Pass 

FAIL_TEXT =Fai 1 

PASS_VALUE=P 

|FAI  L_VALUE  =  F 


Figure  11-4  ARSGUI. CFG 


AUDIT  section 

The  AUDIT  section  contains  one  record,  the  FOLDERS  record.  The  FOLDERS 
record  contains  a  comma-separated  list  of  folder  section  names.  You  must  create 
an  additional  section  in  the  DAF  file  for  each  folder  section  named  in  the 
FOLDERS  record.  The  total  number  of  characters  in  the  FOLDERS  record  must 
not  exceed  255. 
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FOLDER  section 

Each  FOLDER  section  contains  the  following  records: 

►  FOLDER  specifies  the  name  of  the  folder,  exactly  as  it  appears  in 
OnDemand.  The  FOLDER  record  is  required. 

►  AUDIT_FIELD  specifies  the  name  of  the  folder  field  used  to  audit  documents, 
exactly  as  it  appears  in  OnDemand.  The  AUDIT_FIELD  record  is  required. 

►  PASS_TEXT  is  the  caption  that  appears  on  the  command  button  used  to 
mark  a  document  that  passes  an  audit.  The  PASS_TEXT  record  is  optional 
and  if  not  defined.  The  default  value  is  Pass.  Keep  in  mind  this  is  a  small 
button  and  any  word  over  6  or  7  letters  will  not  fit  on  the  button. 

►  FAIL_TEXT  is  the  caption  that  appears  on  the  command  button  used  to  mark 
a  document  that  fails  an  audit.  The  FAIL_TEXT  record  is  optional  and  if  not 
defined,  the  default  value  is  Fail.  Keep  in  mind  that  this  is  a  small  button  and 
any  word  over  6  or  7  letters  will  not  fit  on  the  button. 

►  PASS_VALUE  is  the  value  that  is  stored  in  the  database  for  documents  that 
pass  an  audit.  This  value  is  stored  in  the  application  group  field  and  must 
match  one  of  the  mapped  fields.  The  PASS_VALUE  record  is  required. 

►  FAIL_VALUE  is  the  value  that  is  stored  in  the  database  for  documents  that  fail 
an  audit.  This  value  is  stored  in  the  application  group  field  and  must  match 
one  of  the  mapped  fields.  The  FAIL_VALUE  record  is  required. 


Note:  You  must  restart  the  OnDemand  client  after  creating  this  file. 
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11.1.6  View  the  folders 


Notice  that  now,  when  the  user  Auditor  logs  into  the  “Credit  Card  Statements 
Auditor”  folder,  there  are  two  buttons  (on  the  bottom  right)  that  allow  for  the 
updating  of  the  status  field. 


^Hdr  |  |  10 

Figure  11-5  Auditors  view  of  the  folder 
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In  Figure  1 1  -6,  when  the  customer  (Summit  Sports)  queries  the  server,  they  are 
limited  to  what  they  can  see.  The  customer  does  not  see  the  status  buttons,  or 
the  status  of  the  documents.  Notice  that  this  customer  only  sees  their  statements 
and  only  those  statements  that  have  been  “passed”  by  the  auditor. 


Figure  11-6  Customer  view  of  the  folder 

In  closing,  this  document  audit  facility  may  be  a  useful  way  of  auditing  documents 
in  OnDemand.  We  have  only  set  up  two  status  fields  in  our  example,  because 
there  is  a  limitation  to  two  status  buttons  per  folder.  To  take  this  example  further, 
it  is  possible  to  set  up  multiple  folders  each  with  their  own  distinct  status  buttons. 
By  doing  so,  it  would  be  possible  to  route  a  document  through  a  series  of 
auditing.  You  could  define  various  users,  each  with  a  different  auditing 
responsibility. 

For  example,  a  particular  user  would  be  responsible  for  pulling  up  all  failed 
documents  and  placing  them  in  some  other  status.  In  order  to  do  this,  each 
status  must  be  mapped  in  the  application  group,  and  each  folder  must  be 
specified  within  the  appropriate  users  arsgui .  cfg.  It  would  also  be  important  to 
set  each  users  with  the  correct  search  and  update  permissions  in  the  application 
group. 
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11.2  Related  Documents  feature 


The  Related  Documents  feature  is  a  relatively  unknown  but  useful  feature  which 
is  available  within  the  standard  OnDemand  Windows  client.  Related  Documents 
feature  give  users  the  ability  to  retrieve  a  document  and  then  based  on  the 
content  of  that  document,  they  can  search  for  other  related  documents  stored  in 
OnDemand  with  a  simple  one  button  click.  The  details  of  how  to  configure  the 
Windows  client  for  Related  Documents  are  supplied  within  the  section  “Related 
Documents”,  in  the  chapter  “Windows  32-bit  GUI  Customization  Guide”,  in 
IBM  Content  Manager  OnDemand  -  Windows  Client  Customization  Guide  and 
Reference,  SC27-0837.  The  following  sections  contain  extracts  from  the  guide 
along  with  important  tips  and  practical  examples  of  how  to  configure  this  feature. 


11.2.1  How  does  it  work? 

In  principle,  the  Related  Documents  feature  is  designed  so  that  you  can  load  two 
completely  different  types  of  documents  in  OnDemand  and  link  them  together 
within  the  OnDemand  client.  For  example,  a  hypothetical  finance  company 
produces  quarterly  finance  reports  for  each  of  its  clients.  In  conjunction  with 
these  reports,  the  company  produces  a  summary  sheet  containing  a  sub  set  of 
reference  numbers  for  these  financial  reports.  It  is  possible  using  the  Related 
Documents  feature  to  access  the  financial  reports  with  a  single  click  from  within 
the  summary  sheet. 

The  way  in  which  this  is  done  is  by  the  user  selecting  text  from  within  a  document 
and  then  clicking  on  the  Related  Documents  icon  which  is  on  the  task  bar  when 
Related  Documents  is  configured  for  that  folder.  The  text  which  was  selected  is 
then  used  as  the  search  criteria  on  another  folder  and  the  first  document  in  the 
hit  list  from  this  search  is  displayed  in  the  client  along  side  the  document  already 
open. 

Using  the  preceding  example,  the  summary  sheet  must  be  a  document  type 
which  allows  text  to  be  selected  within  the  OnDemand  client;  Related  Documents 
does  not  work  if  the  summary  sheet  is  either  PDF  or  image  data.  Figure  11-7 
shows  an  OnDemand  Windows  client  configured  to  use  the  Related  Documents 
feature  and  illustrates  a  line  data  document  which  has  been  used  to  retrieve  a 
letter  and  a  credit  card  statement  using  the  Related  Documents  icon.  The 
Related  Document  icon  for  this  example  is  a  star  on  the  right  hand  side  of  the  tool 
bar.  This  can  be  replaced  with  any  icon  design  you  choose. 
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Figure  11-7  Related  Documents  search 


11.2.2  Configuring  Related  Documents 

In  order  to  configure  an  OnDemand  Windows  client  to  enable  the  Related 
Documents  feature,  it  is  necessary  to  edit  the  registry  of  the  Windows  machine 
that  the  client  is  installed  on.  A  detailed  description  of  the  registry  keys  and  string 
values  which  must  be  added  can  be  found  on  Section  “Related  Documents”,  in 
Chapter  “Windows  32-bit  GUI  Customization  Guide”,  in  IBM  Content  Manager 
OnDemand  -  Windows  Client  Customization  Guide  and  Reference,  SC27-0837. 
We  have  supplied  a  sample  registry  file  (import. reg)  in  Example  11-1  which  can 
be  edited  with  your  own  folder  names,  fields  and  icon  values  and  then  imported 
into  the  registry. 

Example  11-1  Example  of  a  registry  import  file  (import. reg) 

Windows  Registry  Editor  Version  5.00 

[HKEY_CURRENT_USER\Software\IBM\0nDemand32\Cl i ent\Rel  atedDocs] 

"Related"  =  "  Letters ,  Baxter11 

[HKEY_CURRENT_USER\Software\IBM\0nDemand32\Client\RelatedDocs\Baxter] 
"MenuText"="Rel ated  Check" 
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"Bi  tmapDl  1  "="c:\\rel  docsWextaddl  1  .dll" 

"BitmapResid"="135" 

"Rel atedFol der"=“ Cheque  Images" 

"Fields"  =  "Amoiint=eq\\%s" 

"Arrange"="v" 

" Fol ders"=" Baxter*\\Credi t*" 

[HKEY_CURRENT_USER\Software\IBM\0nDemand32\Client\RelatedDocs\Letters] 
"MenuText"="Fi nanci al  Report" 

"BitmapDLL"="c:\\rel  docsWextaddl  1  .dll" 

"BitmapResid"="135" 

" Folders"=" Letters" 

"Rel atedFol der"="Fi nanci al  Report" 

"Fi el ds"=" Reference  Number=eq\\%s" 

"Arrange"="v" 


The  process  for  importing  a  file  into  the  registry  is  as  follows: 

1 .  Create  a  registry  file  using  the  sample  in  Example  11-1.  The  file  should  have 
the  extension  of  .reg. 

1.  Click  Start — >  Run... 

2.  Type  regedi  t  into  the  box  which  appears 

3.  Click  Registry  — >  Import  Registry  File  ...  from  within  the  register  editor  tool. 

4.  Select  the  registry  file  which  you  created  in  step  1  and  click  Open. 

After  importing  the  registry  keys  and  string  values,  the  structure  of  this  part  of  the 
registry  should  look  similar  to  Figure  1 1  -8. 


Figure  11-8  Registry  structure  for  Related  Documents  feature 
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11.3  Store  OnDemand 


Store  OnDemand  is  one  of  the  latest  additions  to  the  list  of  OnDemand  services 
offerings.  In  simple  terms,  Store  OnDemand  is  a  graphical  application  which 
allows  a  user  to  index  and  store  any  PC  document  into  OnDemand.  It  is  designed 
for  the  storing  of  single  documents  rather  then  the  main  design  point  of 
OnDemand  which  is  loading  large  quantities  of  report  files  in  batch. 


11.3.1  Why  is  it  needed? 

Previously,  in  order  to  load  a  single  document  into  OnDemand,  it  was  necessary 
to  load  it  via  the  generic  indexer.  The  basic  process  to  follow  is  to  produce  an 
index  file  similar  to  Example  1 1  -2  and  then  with  the  index  file  and  the  document 
file,  the  arsload  program  is  used  to  load  the  document  into  OnDemand. 

Typically,  the  only  place  that  the  arsload  program  can  run  is  on  the  server,  and 
therefore  users  might  send  their  files  which  require  loading  into  OnDemand  to  an 
administrator  who  would  initiate  a  daily  batch  load  of  these  documents.  With  the 
Store  OnDemand  services  offering,  one  no  longer  needs  to  rely  on  a  system 
administrator  to  store  a  single  document.  See  the  next  section  to  learn  exactly 
what  the  service  offering  provides. 

Example  11-2  Sample  Generic  index  file 

COMMENT:  OnDemand  Generic  Index  File  Format 

COMMENT:  This  file  has  been  generated  by  the  arsdoc  command 

COMMENT:  February  25,  2002  09:04:04 

COMMENT: 

C0DEPAGE:5348 

COMMENT: 

I GN0RE_P  RE  P  ROC  ESS  I NG : 1 
COMMENT: 

G  R0U  P_F I E  LD_N AM  E : n  ame 
GR0UP_FIELD_VALUE: SMITH  CYCLERY  CO 
GR0UP_FIELD_NAME: account 
GR0UP_FIELD_VALUE: 000-000-000 
GROUP_FIELD_NAME:crd_date 
GR0UP_FI ELD_VALUE : 19950303 
GR0UP_FIELD_NAME: balance 
GR0UP_FIELD_VALUE: 1058. 110000 
GR0UP_0FFSET : 0 
GR0UP_LENGTH: 2800 

GROUP_FILENAME:c:\temp\credit.l. Baxter  Bay  Credi t. Baxter  Bay  Credit. out 
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11.3.2  What  does  it  do? 


Store  OnDemand  is  a  client  based  application  which  allows  users  to  initiate  the 
storing  of  documents  into  OnDemand  directly  rather  than  going  through  an 
administrator.  The  process  of  storing  a  document  into  OnDemand  is  as  follows: 

1 .  Launch  the  Store  OnDemand  application.  The  user  is  required  to  logon  using 
an  OnDemand  user  ID  and  password.  The  screen  shown  in  Figure  1 1-9  is 
displayed. 

2.  Locate  the  document  that  the  user  wish  to  store  into  OnDemand.  Either  click 
Locate  ..  to  find  the  document,  or  it  can  be  found  in  a  Windows  Explorer 
window  and  drag  and  dropped  onto  the  Store  OnDemand  window. 


Figure  11-9  Store  OnDemand  screen  display 

3.  Select  the  application  group  and  application  which  the  document  should  be 
stored  from  the  lists. 
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4.  When  the  application  group  is  selected,  the  index  fields  required  for  this 
document  will  be  displayed.  Either  enter  the  index  fields  or  click  View  ...  and 
cut  and  paste  the  index  values  from  the  document  in  order  to  reduce  the 
opportunity  for  user  error. 

5.  Click  Store  Document  to  load  the  document  into  OnDemand. 


Note:  There  is  data  verification  functions  within  Store  OnDemand  in  order  to 
ensure  that  data  entered  is  in  the  correct  format  and  type  in  order  to  further 
reduce  the  possibility  of  entering  incorrect  indexes.  The  Store  Document 
bottom  is  greyed  out  until  this  validation  criteria  is  satisfied  or  so  storing  will 
not  be  possible.  Guidance  of  this  criteria  is  provided  in  the  Store  OnDemand 
window. 


Store  OnDemand  stores  documents  to  Version  7.1  OnDemand  servers  on  UNIX, 
Windows,  z/OS,  and  Version  5.2  servers  on  OS/400.  It  requires  DB2  to  be 
installed  on  the  PC  and  a  database  to  database  connection  to  the  server. 

For  more  information  on  the  Store  OnDemand  services  offering,  or  to  obtain  the 
Store  OnDemand  code,  please  contact  your  local  IBM  sales  representatives. 


11.4  Batch  OnDemand  commands  in  z/OS 

The  OnDemand  commands  are  designed  to  be  entered  from  a  UNIX  or  NT 
command  line.  The  ARSLOAD  and  ARSADMIN  can  be  called  as  a  program  with  the 
proper  JCL  provided  and  the  output  is  written  to  DD  sysout.  Other  commands 
such  as  ARSDATE,  ARSADM  can  be  run  as  a  batch  job  too  using  the  BPXBATCH 
program. 

The  example  in  Figure  11-10  shows  how  to  run  ARSDATE  command  as  a  batch 
job.  The  executable  file  ARSDATE  itself  resides  in  the  /usr/1  pp/ars/bi  n  directory 
in  the  HFS  of  the  UNIX  System  Services.  The  output  will  be  written  to  the 
STDOUT  statement  which  points  to  a  outputfile  in  the  HFS  directory 
/tmp/arssockt.std.  This  file  must  be  accessible  or  the  user  running  the  BPXBATCH 
program  must  have  the  proper  authority  to  create  this  file. 
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//ARSDATE  JOB  (QFTAO000, B123) , 

//  ’Henry  Martens ' , HSGCLflSS=0J CLASS=U, 

//  N0TIFY=8:SYSUIDJ  USER=TEAM5 

//STEP1 

EXEC  PGM=BPXBATCH,  REGION=0MJ 

II 

Of. 

a= 

o_ 

PGM  /usr/lpp/ars/bin/arsdate  11/23/02' 

//STEPLIB 

DD  D I SP=SHRJ DSN=OD390. V710. DBS. SARSLOAD 

// 

DD  D I SP=SHRJ DSN=ICCDB2, SDSNEXIT 

// 

DD  D I SP=SHRJ DSN= ICCDB2 . SDSNLOAD 

//SYSPRINT 

DD  SYS0UT=* 

//SYSABEND 

DD  SYS0UT=* 

//SYSOUT 

DD  SYS0UT=* 

//DSNAOINI 

DD  PATH=’/etc/ars/cli.  ini 1 

//STDERR 

DD  PATH= ’/tmp/arssockt, stderr ' , PATHMODE=SIRWXUJ 

// 

PATH0PTS=  [OWRONLYj OCREAT, OAPPEND) , PATHDISP= (KEEP, KEEP] 

//STDOUT 

DD  PATH= ’/tmp/arssockt . stdou t ’ , PATHMODE=SIRWXU, 

// 

PATH0PTS=  (OWRONLY, OCREAT, OAPPEND] ,  PATHDISP= (KEEP,  KEEP] 

//STDENV 

DD  PATH= ’ /usr/lpp/ars/conf ig/arssockd , stdenv ' , 

// 

PATH0PTS=0RD0NLY 

Figure  11-10  BPXBATCH  sample  program 


11.5  Testing  PDF  indexer  in  z/OS 

This  is  a  good  way  to  test  the  PDF  indexer  is  to  run  the  indexer  as  a  batch  job 
without  loading  the  data  to  the  database  with  the  ARSPDOCI  program.  The 
ARSPDOCI  is  shipped  with  the  basic  code.  Your  instance  ARSSOCKD  must  not  be  up. 
The  JCL  sample  in  Figure  11-11  shows  how  to  run  the  ARSPDOCI  program. 
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//ARSPDFLO  JC 

(QFTA0000, B123) , 

//  ’Henry  Martens MSGCLASS=0, CLASS=U, 

//  N0TIFY=&SYSUID,USER=TERM5 

//STEP1 

(EC  PGM=ARSPDOCI,REGION=0M, 

//  PARM= ' parmdd=DDN: PAR  0UTPUTDD=hfs: /tmp/pdf . out  INDEXDD=hfs: /tmp/pdf 

// 

.  ind ' 

//STEPLIB 

DISP=SHR, DSN=TEAM5, ODMP710, SARSLOAD 

//SYSPRINT 

SYS0UT=* 

//xxxxxxxxxxxxxxxxxx*xxxxxxxxxxxx*xxxxxxxxxxx*xxxxxxxxxxxx*xxxx 

//*  PDF 

indexer  parmfile  contains  the  indexer  parameters  * 

. . . . . 

//PAR 

DSN=TEAM5. PDFPARM1, DISP=SHR 

//SYSABEND 

)D  SYS0UT=* 

//SYSOUT 

)D  SYS0UT=* 

//SYSTERM 

SYS0UT=* 

//INPUT 

DISP=0LD, DSN=TEAM5. PDF4011 . DATA 

//St!********************************************** 

//*  PDF 

indexer  files. 

//*********************************************** 

//ADOBERES 

DSN=TEAM5. PDFLIB. RESOURCE. INDEX (ADOBERES) ,  DISP=SHR 

//ADOBEFNT 

)D  DSN=TEAM5. PDF405. PLUSP1C. ADOBEFNT. LST, DISP=SHR 

//TEMPATTR 

)D  DSN=TEAM5. PDF405. PLUSP1C. TEMPATTR, DISP=SHR 

Figure  11-11  ARSPDOCI  sample  JCL 


The  PAR  DD  file  contains  the  parameter  for  the  indexer  (Example  11-3).  You  can 
cut  and  paste  this  information  from  the  Application  panel  indexer  information. 

Example  1 1  -3  Parameter  file  for  ARSPDOCI  program 
C00RDINATES=IN 

TRIGGER1=UL(5.67,0.85),LR(6. 18,1.09),*,' Page  1' 

FIELD1=UL(4. 68,0. 85), LR(5. 71,1. 06), 0,  (TRIGGERS, BASE=0) 

FIELD2=UL(4. 17,1. 22), LR(7. 39,1. 47),  1,  (TRIGGERS, BASE=0) 

FIELD3=UL(5. 61,1. 43), LR(6. 49,1. 71),  1,  (TRIGGERS, BASE=0) 

FIELD4=UL(5. 14,1. 46), LR(5. 61,1. 64),  1,  (TRIGGERS, BASE=0) 

I NDEX1=  1  relate' , FIELD1,  (TYPE=GR0UP) 

INDEX2= ' rname ' ,FIELD2, (TYPE=GR0UP) 

INDEX3= ' rpl an ' ,FIELD3, (TYPE=GR0UP) 

INDEX4= ' rrefcode 1 ,FIELD4, (TYPE=GR0UP) 

INDEXSTARTBY=10 
INDEXDD=hfs :/tmp/pdf . i nd 
INPUTDD=DDN : INPUT 
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A 

access.  To  obtain  data  from  or  to  put  data  in 
storage. 

ACIF.  Advanced  Function  Presentation 
Conversion  and  Indexing  Facility 

Acrobat.  The  Adobe  viewer  for  PDF  files. 
Acrobat  is  similar  to  the  IBM  AFP  Workbench, 
that  is,  a  stand-alone  viewer.  Acrobat  also 
supports  a  robust  set  of  APIs.  It  is  through 
these  APIs  that  Acrobat  is  integrated  with  the 
OnDemand  client  program. 

active  log  file.  The  subset  of  files  consisting 
of  primary  log  files  and  secondary  log  files  that 
are  currently  needed  by  the  database 
manager  for  rollbacks  and  recovery. 

active  policy  set.  In  TSM,  the  policy  set  within 
the  policy  domain  that  contains  the  most 
recently  activated  policy  currently  in  use  by  all 
client  nodes  that  have  been  assigned  to  that 
policy  domain.  See  Policy  Set. 

active  storage  node.  In  a  storage  set,  the 
storage  node  that  is  currently  being  used  to 
load  data. 

adapter.  A  part  that  electrically  or  physically 
connects  a  device  to  a  computer  or  to  another 
device. 

addressable  point.  Any  point  in  a 
presentation  surface  that  can  be  identified  by 
a  coordinate  from  the  coordinate  system  of  the 
presentation  medium.  See  also  Pel. 


administrative  client.  (1)  In  OnDemand,  the 
program  that  provides  administrators  with 
functions  to  maintain  OnDemand  groups, 
users,  printers,  applications,  application 
groups,  storage  sets,  and  folders.  (2)  In  TSM, 
the  program  that  allows  administrators  to 
control  and  monitor  the  server  through 
administrator  commands. 

ADSM.  ADSTAR  ® Distributed  Storage 
Manager 

ADSTAR  Distributed  Storage  Manager.  A 

program  that  provides  storage  management 
for  archived  files.  See  Tivoli  Storage  Manager. 

Advanced  Function  Presentation  (AFP).  A 

set  of  licensed  programs  that  use  the 
all-points-addressable  concept  to  print  data  on 
a  wide  variety  of  printers  or  display  data  on  a 
variety  of  display  devices.  AFP  also  includes 
creating,  formatting,  archiving,  viewing, 
retrieving,  and  distributing  information. 

Advanced  Function  Presentation 
Application  Programming  Interface  (AFP 

API).  An  AFP  program  shipped  with  PSF/MVS 
2.1.1  and  PSF/VM  2.1 .1  that  creates  the  AFP 
data  stream  from  the  COBOL  and  PL/1 
high-level  programming  languages. 

Advanced  Function  Presentation 
Conversion  and  Indexing  Facility.  A 

program  shipped  with  OnDemand  that  you  can 
use  to  convert  a  print  file  into  a  MO:DCA-P 
document,  to  retrieve  resources  used  by  the 
document,  and  to  index  the  file  for  later 
retrieval  and  viewing. 
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Advanced  Function  Presentation  data 
stream  (AFP  data  stream).  A  presentation 
data  stream  that  is  processed  in  the  AFP 
environment.  MO:DCA-P  is  the  strategic  AFP 
interchange  data  stream.  IPDS  » is  the 
strategic  AFP  printer  data  stream. 

AFP.  Advanced  Function  Presentation 

AFP  API.  Advanced  Function  Presentation 
Application  Programming  Interface 

AFPDS.  A  term  formerly  used  to  identify  the 
composed  page,  MO:DCA-P-based  data 
stream  interchanged  in  AFP  environments. 

AIX.  (1)  Advanced  Interactive  Executive  (2) 
IBM’s  version  of  the  UNIX  operating  system. 

AIX  Acrobat  Libraries.  A  subset  of  the 
Acrobat  Libraries  ported  to  AIX  for  use  by 
OnDemand. 

all-points-addressable  (APA).  The  capability 
to  address,  reference,  and  position  data 
elements  at  any  addressable  position  in  a 
presentation  space  or  on  a  physical  medium. 
An  example  of  all  points  addressability  is  the 
positioning  of  text,  graphics,  and  images  at 
any  addressable  point  on  the  physical 
medium.  See  also  Picture  Element. 

all-points-addressable  mode.  Synonym  for 
Page  Mode 

alphabetic  character.  A  letter  or  other 
symbol,  excluding  digits,  used  in  a  language. 
Usually  the  uppercase  and  lowercase  letters  A 
through  Z  plus  other  special  symbols  (such  as 
$  and  _)  allowed  by  a  particular  language.  See 
also  Alphanumeric  Character. 


alphanumeric  character.  Consisting  of 
letters,  numbers,  and  often  other  symbols, 
such  as  punctuation  marks  and  mathematical 
symbols.  See  also  Alphabetic  Character. 

alphanumeric  string.  A  sequence  of 
characters  consisting  solely  of  the  letters  a 
through  z  and  the  numerals  0  through  9. 

American  National  Standards  Institute 
(ANSI).  An  organization  for  the  purpose  of 
establishing  voluntary  industry  standards. 

anchor  point.  The  point  in  a  document  that 
signals  to  ACIF  the  beginning  of  a  group  of 
pages,  after  which  it  adds  indexing  structured 
fields  to  delineate  this  group. 

ANSI.  American  National  Standards  Institute 

ANSI  carriage  control  character.  A 

character  that  specifies  that  a  write,  space,  or 
skip  operation  should  be  performed  before 
printing  the  line  containing  the  carriage 
control.  ANSI  carriage  control  characters  are 
encoded  in  ASCII  or  EBCDIC. 

APA.  All  points  addressable 

API.  Application  Program  Interface 

application.  In  OnDemand,  an  object  that 
describes  the  physical  attributes  of  a  report  or 
input  file,  such  as  the  type  of  data  found  in  the 
input  file,  the  code  page,  and  whether  the 
input  data  contains  carriage  control 
characters.  An  application  also  contains 
instructions  that  the  data  indexing  and  loading 
programs  use  to  process  the  input  data.  Most 
customers  define  an  application  for  each 
different  output  print  data  stream  or  source  of 
data  that  they  plan  to  store  in  OnDemand. 
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application  group.  A  collection  of  one  or 
more  OnDemand  applications  that  have 
similar  indexing  and  storage  management 
requirements.  For  example,  two  reports  that 
can  be  retrieved  using  the  same  index  fields 
and  that  are  to  be  maintained  by  the  system  in 
the  same  storage  locations  for  the  same 
length  of  time  could  be  placed  in  the  same 
application  group. 

Application  Program  Interface  (API).  A 

formally  defined  programming  language 
interface  that  is  between  a  program  and  the 
user  of  a  program. 

archive  copy  group.  In  TSM,  a  policy  object 
containing  attributes  that  control  the 
generation,  destination,  and  expiration  of 
archive  files.  An  archive  copy  group  belongs  to 
a  management  class. 

archive  log  file.  The  subject  of  files  consisting 
of  primary  log  files  and  secondary  log  files  that 
are  no  longer  needed  for  normal  database 
processing. 

archive  media.  Devices  and  volumes  on 
which  the  long-term  or  backup  copy  of  a  report 
is  stored.  For  example,  an  optical  storage 
library  is  one  type  of  archive  media  supported 
by  OnDemand. 

archive  storage.  The  storage  in  which  the 
long-term  or  backup  copy  of  a  report  is 
maintained.  Includes  the  devices  and  volumes 
on  which  the  files  are  stored  and  the 
management  policies  that  determine  how  long 
data  is  maintained  in  archive  storage. 

archive  storage  manager.  The  software 
product  that  manages  archive  media  and 
maintains  files  in  archive  storage.  See  TSM. 


ASCII  (American  Standard  Code  for 
Information  Interchange).  The  standard 
code,  using  a  coded  character  set  consisting 
of  7-bit  coded  characters  (8-bits  including 
parity  check),  that  is  used  for  information 
interchange  among  data  processing  systems, 
data  communication  systems,  and  associated 
equipment.  The  ASCII  set  consists  of  control 
characters  and  graphic  characters.  (A) 

attachment.  A  device  or  feature  attached  to  a 
processing  unit,  including  required  adapters. 
Contrast  with  Adapter. 

authentication.  The  process  of  checking  a 
user’s  password  before  allowing  the  user 
access  to  resources  or  the  server. 

authorize.  (1)  To  grant  to  a  user  the  right  to 
communicate  with  or  make  use  of  a  computer 
system  or  display  station.  (2)  To  give  a  user 
either  complete  or  restricted  access  to  an 
object,  resource,  or  function. 

B 

BCOCA.  Bar  Code  Object  Content 
Architecture 

backend.  In  the  AIX  operating  system,  the 
program  that  sends  output  to  a  particular 
device.  Synonymous  with  Backend  Program. 

backend  program.  Synonym  for  Backend. 

Bar  Code  Object  Content  Architecture.  An 

architected  collection  of  control  structures 
used  to  interchange  and  present  bar  code 
data. 

bitmap.  A  file  that  contains  a  bit-mapped 
graphic. 

BMP.  Bitmap 
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byte.  The  amount  of  storage  required  to 
represent  1  character;  a  byte  is  8  bits. 

C 

cache  storage.  The  storage  in  which  the 
primary  or  short-term  copy  of  a  report  is 
stored.  Usually  disk  storage.  Most  customers 
configure  the  system  to  maintain  the  most 
recent  and  frequently  used  versions  of  reports 
in  cache  storage. 

carriage  control  character.  The  first 
character  of  an  output  record  (line)  that  is  to 
be  printed;  it  determines  how  many  lines 
should  be  skipped  before  the  next  line  is 
printed. 

case-sensitive.  Able  to  distinguish  between 
uppercase  and  lowercase  letters. 

CCITT.  Consultative  Committee  on 
International  Telegraphy  and  Telephone 

CD-ROM.  Compact  disc  read-only  memory 

channel.  A  device  connecting  the  processor 
to  input  and  output  devices. 

channel  adapter.  A  communication  controller 
hardware  unit  used  to  attach  the  controller  to  a 
System/370  --data  channel. 

channel-attached.  (1)  Pertaining  to  devices 
attached  to  a  controlling  unit  by  cables,  rather 
than  by  telecommunication  lines.  (2) 
Synonymous  with  Local. 

character.  A  letter,  digit,  or  other  symbol 
representing,  organizing,  or  controlling  data. 


character  rotation.  The  alignment  of  a 
character  with  respect  to  its  character 
baseline,  measured  in  degrees  in  a  clockwise 
direction.  Examples  are  0°,90°,  180°,  and 
270°.  Zero-degree  character  rotation  exists 
when  a  character  is  in  its  customary  alignment 
with  the  baseline. 

character  set.  A  group  of  characters  used  for 
a  specific  reason;  for  example,  the  set  of 
characters  a  printer  can  print  or  a  keyboard 
can  support. 

click.  To  press  the  left  mouse  button  while 
pointing  to  an  object  such  as  a  command 
button  or  a  toolbar  button. 

client.  (1)  In  a  distributed  file  system 
environment,  a  system  that  is  dependent  on  a 
server  to  provide  it  with  programs  or  access  to 
programs.  (2)  A  personal  computer  connected 
to  a  network  running  OnDemand  software  that 
can  log  on  and  query  the  library  server, 
retrieve  documents  from  OnDemand,  and 
view  and  print  documents. 

client  domain.  The  set  of  optical  drives  and 
storage  volumes  used  by  TSM  to  store  report 
files  and  resources  belonging  to  an  application 
group. 

client  node.  An  application  group  that  has 
been  registered  to  the  TSM  server. 

COBOL.  Common  business-oriented 
language.  A  high-level  programming 
language,  based  on  English,  that  is  used 
primarily  for  business  applications. 

code  page.  An  ordered  set  of  up  to  256 
predefined  display  symbols.  The  first  32  code 
points  of  each  code  page  are  reserved  for 
control  codes  and  are  the  same  for  all  code 
pages,  leaving  up  to  224  distinct  display 
symbols  per  page. 
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Code  Page  Global  Identifier  (CPGID).  A 

unique  code  page  identifier  that  can  be 
expressed  as  either  a  two-byte  binary  or  a 
five-digit  decimal  value. 

code  point.  A  character  within  a  code  page. 

coded  font.  An  AFP  font  that  associates  a 
code  page  and  a  font  character  set. 

command.  A  request  to  perform  an  operation 
or  run  a  program.  When  parameters  values, 
flags,  or  other  operands  are  associated  with  a 
command,  the  resulting  character  string  is  a 
single  command. 

command  line.  The  area  of  the  screen  where 
commands  are  displayed  as  they  are  typed. 

communication  method.  The  method  used 
by  OnDemand  and  TSM  to  exchange 
information. 

communication  protocol.  A  set  of  defined 
interfaces  that  allow  computers  to 
communicate  with  each  other. 

compact  disc  read-only  memory 
(CD-ROM).  High  capacity  read-only  memory 
in  the  form  of  an  optically  read  compact  disk. 

composed  page.  In  Advanced  Function 
Presentation,  a  page  that  can  be  printed  only 
on  an  all-points-addressable  output  medium.  It 
may  contain  composed  text  and  raster 
images. 

composed-text  data  file.  A  file  containing  text 
data  and  text  control  information  that  dictates 
the  format,  placement,  and  appearance  of  the 
data  to  be  printed. 


compression.  A  technique  for  removing 
strings  of  duplicate  characters,  gaps,  empty 
fields,  and  trailing  blanks  before  transmitting 
data. 

concatenate.  (1)  To  link  together.  (2)  To  join 
two  character  strings. 

concatenated  field.  Two  or  more  fields  from  a 
physical  file  record  format  that  have  been 
combined  to  make  one  field  in  a  logical  file 
record  format. 

conditional  processing.  A  page  definition 
function  that  allows  input  data  records  to 
partially  control  their  own  formatting. 

configuration.  The  process  of  describing  to  a 
system  the  devices,  optional  features,  and 
program  products  that  have  been  installed  so 
that  these  features  can  be  used.  Contrast  with 
Customization. 

configuration  file.  A  file  that  specifies  the 
characteristics  of  a  system  or  subsystem;  for 
example,  the  operating  system  queueing 
system. 

configure.  To  describe  to  a  system  the 
devices,  optional  features,  and  licensed 
programs  installed  on  a  system. 

console.  The  main  operating  system  display 
station. 

constant.  A  data  item  with  a  value  that  does 
not  change  during  the  running  of  a  program. 
Contrast  with  Variable. 

Consultative  Committee  on  International 
Telegraphy  and  Telephone  (CCITT).  A 

United  Nations  Specialized  Standards  group 
whose  membership  includes  common  carriers 
concerned 
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with  devising  and  proposing  recommendations 
for  international  telecommunications 
representing  alphabets,  graphics,  control 
information,  and  other  fundamental 
information  interchange  issues. 

Content  Manager.  A  comprehensive  set  of 
Web-enabled,  integrated  software  solutions 
from  IBM  for  managing  information  and 
making  it  available  to  anyone,  anywhere. 

control  character.  A  character  that  is  not  a 
graphic  character  such  as  a  letter,  number,  or 
punctuation  mark.  Such  characters  are  called 
control  characters  because  they  frequently  act 
to  control  a  peripheral  device. 

controller.  A  device  that  coordinates  and 
controls  the  operation  of  one  or  more 
input/output  devices,  such  as  workstations, 
and  synchronizes  the  operation  of  the  system 
as  a  whole. 

conversion.  In  programming  languages,  the 
transformation  between  values  that  represent 
the  same  data  item  but  belong  to  different  data 
types. 

copies.  See  Copy  Group. 

copy  group.  In  TSM,  a  policy  object  that 
contains  attributes  that  control  the  generation, 
destination,  and  expiration  of  backup  and 
archive  files.  There  are  two  kinds  of  copy 
groups:  backup  and  archive.  Copy  groups 
belong  to  management  classes. 

copy  storage  pool.  A  named  collection  of 
storage  volumes  that  contains  copies  of  files 
that  reside  in  primary  storage  pools.  Copy 
storage  pools  are  used  to  back  up  the  data 
stored  in  primary  storage  pools. 

CPGID.  Code  Page  Global  Identifier 


customization.  The  process  of  describing 
optional  changes  to  defaults  of  a  software 
program  that  is  already  installed  on  the  system 
and  configured  so  that  it  can  be  used.  Contrast 
with  Configuration. 

customize.  To  describe  the  system,  the 
devices,  programs,  users,  and  user  defaults 
for  a  particular  data  processing  system  or 
network.  Contrast  with  Configure. 

D 

daemon.  In  UNIX,  a  process  begun  by  the 
root  user  or  by  the  root  shell  that  can  be 
stopped  only  by  the  root  user.  Daemon 
processes  generally  provide  services  that 
must  be  available  at  all  times,  such  as  sending 
data  to  the  printer.  A  daemon  runs 
continuously,  looking  for  work  to  do, 
performing  that  work,  and  waiting  for  more 
work.  A  daemon  does  not  have  a  controlling 
terminal  associated  with  it.  The  OnDemand 
data  download  program  (ARSJESD)  is  an 
example  of  a  daemon. 

database.  (1)  The  collection  of  information 
about  all  objects  managed  by  OnDemand, 
including  reports,  groups,  users,  printers, 
application  groups,  storage  sets,  applications, 
and  folders.  (2)  The  collection  of  information 
about  all  objects  managed  by  TSM,  including 
policy  management  objects,  administrators, 
and  client  nodes. 

Database  Managed  Space  (DMS).  A  type  of 
DB2  table  space.  A  DSM  table  space  is 
managed  by  the  database  manager. 

data  set.  Synonym  for  File. 

data  stream.  A  continuous  stream  of  data 
elements  being  transmitted,  or  intended  for 
transmission,  in  character  or  binary-digit  form 
using  a  defined  format. 
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data  transfer.  The  movement,  or  copying,  of 
data  from  one  location  and  the  storage  of  the 
data  at  another  location. 

data  type.  The  type,  format,  or  classification 
of  a  data  object. 

DCF.  Document  Composition  Facility 

decimal.  Pertaining  to  a  system  of  numbers  to 
the  base  10.  The  decimal  digits  range  from  0 
through  9. 

decompression.  A  function  that  expands  data 
to  the  length  that  preceded  data  compression. 
See  also  Compression. 

default.  A  value,  attribute,  or  option  that  is 
assumed  when  no  alternative  is  specified  by 
the  user. 

default  directory.  The  directory  name 
supplied  by  the  operating  system  if  none  is 
specified. 

default  printer.  A  printer  that  accepts  all  the 
printed  output  from  a  display  station  assigned 
to  it. 

default  value.  A  value  stored  in  the  system 
that  is  used  when  no  other  value  is  specified. 
See  also  Default. 

desktop  printer.  In  this  publication,  an  IBM 
LaserPrinter  4019  or  4029,  or  compatible 
printer. 

device  class.  A  named  group  of  TSM  storage 
devices.  Each  device  class  has  a  unique 
name  and  represents  a  device  type  of  disk, 
tape,  or  optical  disk. 

device  driver.  A  program  that  operates  a 
specific  device,  such  as  a  printer,  disk  drive,  or 
display. 


device  type.  A  type  of  TSM  storage  device. 
Each  device  class  must  be  categorized  with 
one  of  the  following  devices  types:  disk,  tape, 
or  optical  disk. 

device-independent.  Pertaining  to  a  function 
that  can  be  accomplished  without  regard  for 
the  characteristics  of  particular  types  of 
devices. 

dialog  box.  An  application  window  on  the 
display  that  requests  information  from  the 
user. 

directory.  (1)  A  type  of  file  containing  the 
names  and  controlling  information  for  other 
files  or  directories.  (2)  A  listing  of  related  files 
arranged  in  a  useful  hierarchy. 

disk  operating  system  (DOS).  An  operating 
system  for  computer  systems  that  use  disks 
and  diskettes  for  auxiliary  storage  of  programs 
and  data. 

Distiller.  A  batch  utility  that  converts 
PostScript  files  to  Adobe  PDF  files.  The 
distiller  runs  under  AIX,  HP-UX,  Sun  Solaris, 
and  Windows  servers. 

DMS.  Database  Managed  Space 

document.  (1)  In  OnDemand,  a  logical 
section  of  a  larger  file,  such  as  an  individual 
invoice  within  a  report  of  thousands  of 
invoices.  A  document  can  also  represent  an 
indexed  group  of  pages  from  a  report.  (2)  A  file 
containing  an  AFP  data  stream  document.  An 
AFP  data  stream  document  is  bounded  by 
Begin  Document  and  End  Document 
structured  fields  and  can  be  created  using  a 
text  formatter  such  as  Document  Composition 
Facility  (DCF). 
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Document  Composition  Facility.  An  IBM 

licensed  program  used  to  prepare  printed 
documents. 

domain.  See  Policy  Domain  or  Client  Domain. 

DOS.  Disk  operating  system 

double-click.  To  rapidly  press  the  left  mouse 
button  twice  while  pointing  to  an  object. 

download.  To  transfer  data  from  one 
computer  for  use  on  another  one.  Typically, 
users  download  from  a  larger  computer  to  a 
diskette  or  fixed  disk  on  a  smaller  computer  or 
from  a  system  unit  to  an  adapter. 

drag.  To  hold  down  the  left  mouse  button 
while  moving  the  mouse. 

driver.  The  end  of  a  stream  closest  to  an 
external  interface.  The  principal  functions  of 
the  driver  are  handling  any  associated  device, 
and  transforming  data  and  information 
between  the  external  device  and  stream. 

E 

EBCDIC.  Extended  Binary-Coded  Decimal 
Interchange  Code.  This  is  the  default  type  of 
data  encoding  in  an  MVS  environment. 
Contrast  with  ASCII. 

EIP.  Enterprise  Information  Portal 

enqueue.  To  place  items  in  a  queue. 

enter.  (1)  An  instruction  to  type  specific 
information  using  the  keyboard.  (2)  A 
keyboard  key  that,  when  pressed,  confirms  or 
initiates  the  selected  command. 


Enterprise  Information  Portal.  An  IBM 

software  product  that  provides  a  coordinated, 
Web-enabled  entry  point  to  what  would 
otherwise  be  disconnected,  incompatible  data 
scattered  across  an  enterprise. 

Enterprise  Storage  Server.  An  IBM  disk 
storage  system  that  provides  industry-leading 
availability,  performance,  manageability,  and 
scalability.  Virtually  all  types  of  servers  can 
concurrently  attach  to  the  Enterprise  Storage 
Server,  including  S/390,  UNIX  servers,  and 
Windows  servers.  As  a  result,  the  Enterprise 
Storage  Server  is  ideal  for  organizations  with 
growing  e-business  operations  that  are  being 
handled  by  multiple  heterogeneous  servers. 

environment  variable.  A  variable  that  is 
included  in  the  current  software  environment 
and  is  therefore  available  to  any  called 
program  that  requests  it. 

error  condition.  The  state  that  results  from  an 
attempt  to  run  instructions  in  a  computer 
program  that  are  not  valid  or  that  operate  on 
data  that  is  not  valid. 

error  log.  A  file  in  a  product  or  system  where 
error  information  is  stored  for  later  access. 

error  log  entry.  In  AIX,  a  record  in  the  system 
error  log  describing  a  hardware  or  software 
failure  and  containing  failure  data  captured  at 
the  time  of  the  failure. 

error  message.  An  indication  that  an  error 
has  been  detected.  (A) 

error  recovery.  The  process  of  correcting  or 
bypassing  the  effects  of  a  fault  to  restore  a 
computer  system  to  a  prescribed  condition.  (T) 
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error  type.  Identifies  whether  an  error  log 
entry  is  for  a  permanent  failure,  temporary 
failure,  performance  degradation,  impending 
loss  of  availability,  or  undetermined  failure. 

ESS.  Enterprise  Storage  Server 

Ethernet.  A  10-megabit  baseband  local  area 
network  using  CSMA/CD  (carrier  sense 
multiple  access  with  collision  detection).  The 
network  allows  multiple  stations  to  access  the 
medium  at  will  without  prior  coordination, 
avoids  contention  by  using  carrier  sense  and 
deference,  and  resolves  contention  by  using 
collision  detection  and  transmission. 

exit  program.  A  user-written  program  that  is 
given  control  during  operation  of  a  system 
function. 

exit  routine.  A  routine  that  receives  control 
when  a  specified  event  occurs,  such  as  an 
error. 

expiration.  The  process  of  deleting  index  data 
and  reports  based  on  storage  management 
information.  The  OnDemand  database 
manager  and  the  storage  managers  run 
expiration  processing  to  remove  data  that  is 
no  longer  needed  from  storage  volumes  and 
reclaim  the  space. 

Extended  Binary-Coded  Decimal 
Interchange  Code  (EBCDIC).  A  coded 
character  set  consisting  of  eight-bit  coded 
characters. 

external  library  resource  (member).  Objects 
that  can  be  used  by  other  program  products 
while  running  print  jobs;  for  example,  coded 
fonts,  code  pages,  font  character  sets,  form 
definitions,  page  definitions,  and  page 
segments.  Synonym  for  Resource  Object. 


external  object.  Synonym  for  Resource 
Object. 

F 

FCB.  Forms  control  buffer 

field.  A  specified  area  in  a  record  used  for  a 
particular  type  of  data;  for  example,  a  group  of 
characters  that  represent  a  customer’s  name. 

file.  (1)  A  named  set  of  records  stored  or 
processed  as  a  unit.  (T)  (2)  The  major  unit  of 
data  storage  and  retrieval.  A  file  consists  of  a 
collection  of  data  in  one  of  several  prescribed 
arrangements  and  described  by  control 
information  to  which  the  operating  system  has 
access. 

file  system.  The  collection  of  files  and  file 
management  structures  on  a  physical  or 
logical  mass  storage  device,  such  as  a 
diskette  or  a  minidisk. 

file  transfer.  In  remote  communications,  the 
transfer  of  a  file  or  files  from  one  system  to 
another  over  a  communications  link. 

File  Transfer  Protocol  (FTP).  In  TCP/IP,  the 
protocol  that  makes  it  possible  to  transfer  data 
among  hosts  and  to  use  foreign  hosts 
indirectly. 

fixed  disk.  A  flat,  circular,  nonremovable  plate 
with  a  magnetizable  surface  layer  on  which 
data  can  be  stored  by  magnetic  recording.  A 
rigid  magnetic  disk. 

fixed-disk  drive.  The  mechanism  used  to 
read  and  write  information  on  a  fixed  disk. 


Glossary  297 


folder.  In  OnDemand,  the  end-user  view  of 
data  stored  in  the  system.  Folders  provide 
users  a  convenient  way  to  find  related 
information,  regardless  of  the  source  of  the 
information  or  where  the  data  is  stored. 

font.  (1)  A  family  of  characters  of  a  given  size 
and  style,  for  example  9-point  Helvetica.  (2)  A 
set  of  characters  in  a  particular  style.  See 
Raster  Font. 

font  character  set.  Part  of  an  AFP  font  that 
contains  the  raster  patterns,  identifiers,  and 
descriptions  of  characters.  Often  synonymous 
with  Character  Set.  See  also  Coded  Font. 

form  definition  (FORMDEF).  A  form  definition 
is  a  resource  used  by  OnDemand.  A  form 
definition  specifies  the  number  of  copies  to  be 
printed,  whether  the  sheet  should  be  printed 
on  both  sides,  the  position  of  a  page  of  data  on 
the  sheet,  text  suppression,  and  overlays  to  be 
used  (if  any).  Synonymous  with  FORMDEF. 

FORMDEF.  Form  Definition 

FSA.  Functional  Subsystem  Application.  A 
collection  of  programs  residing  in  the  FSS 
address  space  that  control  a  device. 

FSI.  Functional  Subsystem  Interface.  An  MVS 
or  OS/390  interface  that  allows 
communication  between  JES  and  a  FSS  and 
FSS  applications.  Download  uses  an  FSI  to 
communicate  with  the  operating  system  and 
JES  to  process  spool  data  sets  created  by 
application  programs. 

FSS.  Functional  Subsystem.  An  MVS  or 
OS/390  subsystem  comprised  of  programs 
residing  in  the  same  address  space  that 
provide  JES-related  functions.  For  example,  a 
print  programs  that  extend  the  scope  of  JES 
processing  could  be  defined  as  a  FSS. 


FTP.  File  Transfer  Protocol 

G 

GB.  Gigabyte 

GIF.  Graphic  Interchange  Format 

gigabyte.  A  unit  of  memory  or  space 
measurement  equal  to  approximately  one 
billion  bytes.  One  gigabyte  equals  1,000 
megabytes. 

GOCA.  Graphic  Object  Content  Architecture 

graphic.  A  symbol  produced  by  a  process 
such  as  handwriting,  drawing,  or  printing.  (I) 
(A) 

graphic  character.  A  character  that  can  be 
displayed  or  printed. 

Graphic  Object  Content  Architecture.  An 

architecture  that  provides  a  collection  of 
graphics  values  and  control  structures  used  to 
interchange  and  present  graphics  data. 

Graphical  User  Interface.  A  type  of  user 
interface  that  takes  advantage  of  a 
high-resolution  monitor,  including  some 
combination  of  graphics,  the  use  of  pointing 
devices,  menu  bars,  overlapping  windows, 
and  icons. 

graphics.  A  type  of  data  created  from  such 
fundamental  drawing  units  such  as  lines, 
curves,  polygons,  and  so  forth. 

Graphic  Interchange  Format  (GIF).  A 

bit-mapped  color  graphics  file  format  for  IBM 
and  IBM-compatible  computers.  GIF  employs 
an  efficient  compression  technique  for  high 
resolution  graphics. 
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group.  (1)  A  named  collection  of  sequential 
pages  that  form  a  logical  subset  of  a 
document.  (2)  A  named  collection  of  users 
assigned  a  specific  role  on  the  system  or 
belonging  to  a  specific  department. 

GUI.  Graphical  user  interface 

H 

hardware.  The  physical  equipment  of 
computing  and  computer-directed  activities. 
The  physical  components  of  a  computer 
system.  Contrast  with  Software. 

help.  One  or  more  files  of  information  that 
describe  how  to  use  application  software  or 
how  to  perform  a  system  function. 

hex.  Hexadecimal 

hexadecimal  (hex).  Pertaining  to  a  system  of 
numbers  in  the  base  sixteen;  hexadecimal 
digits  range  from  0  (zero)  through  9  (nine)  and 
A  (ten)  through  F  (fifteen). 

host.  (1)  The  primary  or  controlling  computer 
in  the  communications  network.  (2)  See  Host 
System. 

host-based  computer.  (1)  In  a  computer 
network  a  computer  that  provides  end  users 
with  services  such  as  computation  and  data 
bases  and  that  usually  performs  network 
control  functions.  (T)  (2)  The  primary  or 
controlling  computer  in  a  multiple-computer 
installation. 

host  system.  (1)  The  controlling  or  highest 
level  system  in  a  data  communication 
configuration,  for  example,  an  OS/390  system 
is  the  host  system  for  the  terminals  connected 
to  it.  (2)  In  TCP/IP,  a  computer  that  is  a  peer 
system  in  a  network. 


I 

icon.  A  32  by  32  pixel  bitmap  used  by  the 
windows  manager  to  represent  an  application 
or  other  window. 

image.  (1)  An  electronic  representation  of  a 
picture  produced  by  means  of  sensing  light, 
sound,  electron  radiation,  or  other  emanations 
coming  from  the  picture  or  reflected  by  the 
picture.  An  image  can  also  be  generated 
directly  by  software  without  reference  to  an 
existing  picture.  (2)  An  electronic 
representation  of  an  original  document 
recorded  by  a  scanning  device. 

Image  Object  Content  Architecture.  An 

architected  collection  of  constructs  used  to 
interchange  and  present  images. 

index.  (1)  A  process  of  segmenting  a  print  file 
into  uniquely  identifiable  groups  of  pages  (a 
named  collection  of  sequential  pages)  for  later 
retrieval.  (2)  A  process  of  matching  reference 
points  within  a  file  and  creating  structured  field 
tags  within  the  MO:DCA-P  document  and  the 
separate  index  object  file. 

index  object  file.  An  index-information  file 
created  by  ACIF  that  contains  the  Index 
Element  (IEL)  structured  fields,  which  identify 
the  location  of  tagged  groups  in  the  AFP  file. 
The  indexing  tags  are  contained  in  the  Tagged 
Logical  Element  (TLE)  structured  fields. 

indexing.  (1)  A  process  of  segmenting  a  print 
file  into  uniquely  identifiable  groups  of  pages 
(a  named  collection  of  sequential  pages)  for 
later  retrieval.  (2)  In  ACIF,  a  process  of 
matching  reference  points  within  a  file  and 
creating  structured  field  tags  within  the 
MO:DCA-P  document  and  the  separate  index 
object  file. 
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indexing  with  data  values.  Adding  indexing 
tags  to  a  MO:DCA-P  document  using  data  that 
is  already  in  the  document  and  that  is 
consistently  located  in  the  same  place  in  each 
group  of  pages. 

indexing  with  literal  values.  Adding  indexing 
tags  to  a  MO:DCA-P  document  by  assigning 
literal  values  as  indexing  tags,  because  the 
document  is  not  organized  such  that  common 
data  is  located  consistently  throughout  the 
document. 

Infoprint  Manager.  A  sophisticated  IBM  print 
subsystem  that  drives  AFP  printers,  PostScript 
printers,  and  PCL  printers.  Infoprint  Manager 
is  supported  under  AIX,  OS/390,  Windows  NT, 
and  Windows  2000.  Infoprint  Manager 
manages  printer  resources  such  as  fonts, 
images,  electronic  forms,  form  definitions,  and 
page  definitions,  and  provides  error  recovery 
for  print  jobs. 

When  printing  line  data,  Infoprint  Manager 
supports  external  formatting  using  page 
definitions  and  form  definitions.  This  external 
formatting  extends  page  printer  functions  such 
as  electronic  forms  and  use  of  typographic 
fonts  without  any  change  to  applications  that 
generate  the  data. 

informational  message.  (1)  A  message  that 
provides  information  to  the  end-user  or  system 
administrator  but  does  not  require  a  response. 
(2)  A  message  that  is  not  the  result  of  an  error 
condition. 

input  file.  A  file  opened  in  order  to  allow 
records  to  be  read. 

install.  (1)  To  add  a  program,  program  option, 
or  software  program  to  the  system  in  a  manner 
such  that  it  may  be  executed  and  will  interact 
properly  with  all  affected  programs  in  the 
system.  (2)  To  connect  a  piece  of  hardware  to 
the  processor. 


intelligent  printer  data  stream  (IPDS).  An 

all-points-addressable  data  stream  that  allows 
users  to  position  text,  images,  and  graphics  at 
any  defined  point  on  a  printed  page. 

interface.  Hardware,  software,  or  both,  that 
links  systems,  programs,  or  devices. 

Internet.  A  wide  area  network  connecting 
thousands  of  disparate  networks  in  industry, 
education,  government,  and  research.  The 
Internet  network  uses  TCP/IP  as  the  protocol 
for  transmitting  information. 

Internet  Protocol  (IP).  In  TCP/IP,  a  protocol 
that  routes  data  from  its  source  to  its 
destination  in  an  Internet  environment. 

IOCA.  Image  Object  Content  Architecture 

IP.  Internet  Protocol 

IPDS.  Intelligent  printer  data  stream 

J 

job.  One  or  more  related  procedures  or 
programs  grouped  into  a  procedure,  identified 
by  appropriate  job  control  statements. 

job  queue.  A  list  of  jobs  waiting  to  be 
processed  by  the  system. 

Joint  Photographic  Experts  Group  (JPEG). 

An  image  compression  standard  developed  to 
handle  larger  images  with  many  colors.  JPEG 
uses  a  “lossy”  algorithm,  which  means  there  is 
some  loss  of  detail  when  saving  and  viewing 
images  in  this  format.  However,  JPEG  files 
can  offer  as  much  as  35%  improvement  in  file 
size  and  compression. 

JPEG.  See  Joint  Photographic  Experts  Group 

K 
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kernel.  The  part  of  an  operating  system  that 
performs  basic  functions  such  as  allocating 
hardware  resources. 

kernel  extension.  A  program  that  modifies 
parts  of  the  kernel  that  can  be  customized  to 
provide  additional  services  and  calls.  See 
Kernel. 

K-byte.  Kilobyte 

keyword.  Part  of  a  command  operand  that 
consists  of  a  specific  character  string. 

kilobyte  (K-byte).  1024  bytes  in  decimal 
notation  when  referring  to  memory  capacity;  in 
all  other  cases,  it  is  defined  as  1000. 

L 

LAN.  Local  area  network 

LAN  server.  A  data  station  that  provides 
services  to  other  data  stations  on  a  local  area 
network;  for  example,  file  server,  print  server, 
mail  server.  (T) 

laser  printer.  A  nonimpact  printer  that 
creates,  by  means  of  a  laser  beam  directed  on 
a  photosensitive  surface,  a  latent  image  which 
is  then  made  visible  by  toner  and  transferred 
and  fixed  on  paper.  (T) 

Lempel  Ziv  Welsh  (LZW).  A  data 
compression  algorithm.  OnDemand  uses  the 
16-bit  version  of  LZW  to  compress  data. 

library.  System  storage  for  generated  form 
definitions  and  page  definitions. 

library  resource  (member).  A  named 
collection  of  records  or  statements  in  a  library. 


library  resource  name.  A  name  by  which  an 
object  may  be  called  from  a  library  by  AFP  as 
part  of  a  print  job.  Includes  the  2-character 
prefix  for  the  type  of  object,  such  as  PI  for 
page  definitions,  FI  for  form  definitions,  or  01 
for  overlays  (also  known  as  resource  name). 

library  server.  In  OnDemand,  the  workstation 
or  node  that  users  must  go  through  to  access 
the  system.  The  library  server  controls  the 
OnDemand  database. 

licensed  program.  A  separately  priced 
program  and  its  associated  materials  that  bear 
a  copyright  and  are  offered  to  customers 
under  the  terms  and  conditions  of  a  licensing 
agreement. 

line  data.  Data  prepared  for  printing  on  a  line 
printer,  such  as  an  IBM  3800  Model  1  Printing 
Subsystem.  Line  data  is  usually  characterized 
by  carriage-control  characters  and  table 
reference  characters. 

line-data  print  file.  A  file  that  consists  of  line 
data,  optionally  supplemented  by  a  limited  set 
of  structured  fields. 

line  printer.  A  device  that  prints  a  line  of 
characters  as  a  unit.  (I)  (A)  Contrast  with  Page 
Printer. 

literal.  (1 )  A  symbol  or  a  quantity  in  a  source 
program  that  is  itself  data,  rather  than  a 
reference  to  data.  (2)  A  character  string  whose 
value  is  given  by  the  characters  themselves; 
for  example,  the  numeric  literal  7  has  the  value 
7,  and  the  character  literal  CHARACTERS  has 
the  value  CHARACTERS. 
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loading.  The  logical  process  of  archiving 
reports  in  OnDemand.  During  the  loading 
process,  OnDemand  processes  reports, 
creates  index  data,  and  copies  report  data  and 
resources  to  cache  storage  and  archive 
storage. 

local.  Pertaining  to  a  device  accessed  directly 
without  use  of  a  telecommunication  line. 

local  area  network  (LAN).  (1)  A  computer 
network  located  on  a  user’s  premises  within  a 
limited  geographical  area.  Communication 
within  a  local  area  network  is  not  subject  to 
external  regulations;  however,  communication 
across  the  LAN  boundary  may  be  subject  to 
some  form  of  regulation.  (2)  A  network  in 
which  a  set  of  devices  is  connected  to  one 
another  for  communication  and  that  can  be 
connected  to  a  larger  network.  See  also 
Token-Ring  Network. 

logical  volume.  The  combined  space  from  all 
volumes  defined  to  either  the  TSM  database 
or  recovery  log.  The  database  resides  on  one 
logical  volume  and  the  recovery  log  resides  on 
a  different  logical  volume. 

log  file.  A  fixed-length  file  used  to  record 
changes  to  a  database. 

LPD.  Line  Printer  Daemon.  In  TCP/IP,  the 
command  responsible  for  sending  data  from 
the  spooling  directory  to  a  printer. 

LPR.  Line  Printer  Requestor.  In  TCP/IP,  a 
client  command  that  allows  the  local  host  to 
submit  a  file  to  be  printed  on  a  remote  print 
server. 

LZW.  See  Lempel  Ziv  Welsh 

M 

M  byte.  Megabyte 


MB.  Megabyte 

machine  carriage  control  character.  A 

character  that  specifies  that  a  write,  space,  or 
skip  operation  should  be  performed  either 
immediately  or  after  printing  the  line  containing 
the  carriage  control. 

mainframe.  A  large  computer,  particularly  one 
to  which  other  computers  can  be  connected  so 
that  they  can  share  facilities  the  mainframe 
provides.  The  term  usually  refers  to  hardware 
only. 

management  class.  A  logical  area  of  storage 
that  is  managed  by  TSM.  A  management 
class  is  a  policy  object  that  is  a  named 
collection  of  copy  groups.  A  management 
class  can  contain  one  backup  copy  group,  one 
archive  copy  group,  a  backup  and  archive 
copy  group,  or  zero  copy  groups.  Users  can 
bind  each  file  to  a  management  class  to 
specify  how  the  server  should  manage  backup 
versions  or  archive  copies  of  files.  See  Copy 
Group. 

mapping.  (1)  A  list  that  establishes  a 
correspondence  between  items  in  two  groups. 
(2)  The  process  of  linking  database  fields  in  an 
application  group  to  folder  search  and  display 
fields. 

megabyte  (MB).  When  used  with  hard  drive, 
diskette,  or  removable  media  storage 
capacity,  1,000,000  bytes.  When  referring  to 
system  memory  capacity,  1 ,048,576  bytes. 

memory.  Program-addressable  memory  from 
which  instructions  and  other  data  can  be 
loaded  directly  into  registers  for  subsequent 
running  or  processing.  Memory  is  sometimes 
referred  to  as  “storage”. 
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menu  bar.  The  area  at  the  top  of  a  window 
that  contains  choices  that  give  a  user  access 
to  actions  available  in  that  window. 

message.  Information  from  the  system  that 
informs  the  user  of  a  condition  that  may  affect 
further  processing  of  a  current  program. 

migration.  (1)  The  process  of  moving  data 
from  one  computer  system  to  another  without 
converting  the  data.  (2)  The  process  of  moving 
report  files,  resources,  and  index  data  from 
cache  storage  to  long-term  (optical  or  tape) 
storage. 

mirroring.  In  TSM,  a  feature  that  protects 
against  data  loss  with  the  database  or 
recovery  log  by  writing  the  same  data  to 
multiple  disks  at  the  same  time.  Mirroring 
supports  up  to  three  exact  copies  of  each 
database  or  recovery  log. 

Mixed  Object  Document  Content 
Architecture -Presentation  (MO:DCA-P).  (1) 

A  strategic,  architected,  device-independent 
data  stream  for  interchanging  documents.  (2) 
A  printing  data  stream  that  is  a  subset  of  the 
Advanced  Function  Presentation  data  stream. 

MO:DCA-P.  Mixed  Object:  Document  Content 
Architecture  for  Presentation 

mount.  To  make  a  file  system  accessible. 

mouse.  A  hand-held  locator  that  a  user 
operates  by  moving  it  on  a  flat  surface.  It 
allows  the  user  to  select  objects  and  scroll  the 
display  screen  by  pressing  buttons. 

N 

network.  A  collection  of  data  processing 
products  that  are  connected  by 
communication  lines  for  information  exchange 
between  locations. 


Network  File  System  (NFS).  A  protocol 
developed  by  Sun  Microsystems  that  uses 
Internet  Protocol  to  allow  a  set  of  cooperating 
computers  to  access  each  other’s  file  system 
as  if  they  were  local. 

NFS.  Network  File  System 

node.  A  workstation  that  operates  as  an 
OnDemand  library  server  or  object  server  and 
is  connected  to  a  TCP/IP  network. 

notes.  Electronic  comments,  clarifications, 
and  reminders  that  can  be  attached  to  an 
OnDemand  document. 

non-lPDS  printer.  In  this  publication,  a  printer 
that  is  not  channel-attached  and  which  does 
not  accept  the  Intelligent  Printer  Data  Stream. 

numeric.  Pertaining  to  any  of  the  digits  0 
through  9. 

O 

object.  (1)  A  collection  of  structured  fields. 
The  first  structured  field  provides  a 
begin-object  function  and  the  last  structured 
field  provides  an  end-object  function.  The 
object  may  contain  one  or  more  other 
structured  fields  whose  content  consists  of 
one  or  more  data  elements  of  a  particular  data 
type.  An  object  may  be  assigned  a  name, 
which  may  be  used  to  reference  the  object. 
Examples  of  objects  are  text,  graphics,  and 
image  objects.  (2)  A  resource  or  a  sequence 
of  structured  fields  contained  within  a  larger 
entity,  such  as  a  page  segment  or  a  composed 
page.  (3)  A  collection  of  data  referred  to  by  a 
single  name. 

object  server.  In  OnDemand,  a  workstation  or 
node  controlled  by  a  storage  manager  to 
maintain  reports  in  cache  storage,  and 
optionally,  archive  storage. 
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offset.  The  number  of  measuring  units  from 
an  arbitrary  starting  point  in  a  record,  area,  or 
control  block  to  some  other  point. 

online.  Being  controlled  directly  by  or  directly 
communicating  with  the  computer. 

operating  environment.  (1)  The  physical 
environment;  for  example,  temperature, 
humidity,  and  layout.  (2)  All  of  the  basic 
functions  and  the  user  programs  that  can  be 
executed  by  a  store  controller  to  enable  the 
devices  in  the  system  to  perform  specific 
operations.  (3)  The  collection  of  store 
controller  data,  user  programs,  lists,  tables, 
control  blocks,  and  files  that  reside  in  a 
subsystem  store  controller  and  control  its 
operation. 

operating  system.  Software  that  controls  the 
running  of  programs  and  that  also  can  provide 
such  services  as  resource  allocation, 
scheduling,  input  and  output  control,  and  data 
management. 

optical  library.  A  storage  device  that  houses 
optical  disk  drives  and  optical  disks,  and 
contains  a  mechanism  for  moving  optical  disks 
between  a  storage  area  and  optical  disk 
drives. 

optimize.  To  improve  the  speed  of  a  program 
or  to  reduce  the  use  of  storage  during 
processing. 

outline  fonts.  (1)  Fonts  whose  graphic 
character  shapes  are  defined  as  mathematical 
equations  rather  than  by  raster  patterns.  (2) 
Fonts  created  in  the  format  described  in 
Adobe  Type  1  Font  Format,  a  publication 
available  from  Adobe  Systems,  Inc. 
Synonymous  with  Type  1  fonts. 


overlay.  A  collection  of  predefined,  constant 
data  such  as  lines,  shading,  text,  boxes,  or 
logos,  that  is  electronically  composed  and 
stored  as  an  AFP  resource  file  that  can  be 
merged  with  variable  data  on  a  page  while 
printing  or  viewing. 

P 

page.  (1)  A  collection  of  data  that  can  be 
printed  on  one  side  of  a  sheet  of  paper  or  a 
form.  (2)  The  boundary  for  determining  the 
limits  of  printing.  See  also  Logical  Page  and 
Physical  Page.  (3)  Part  of  an  AFP  document 
bracketed  by  a  pair  of  Begin  Page  and  End 
Page  structured  fields. 

page  definition.  A  resource  used  by 
OnDemand  that  defines  the  rules  of 
transforming  line  data  into  composed  pages 
and  text  controls. 

page  printer.  A  device  that  prints  one  page  as 
a  unit.  (I)  (A)  Contrast  with  Line  Printer. 

page  segment.  In  Advanced  Function 
Presentation,  a  resource  that  can  contain  text 
and  images  and  can  be  positioned  on  any 
addressable  point  on  a  page  or  an  electronic 
overlay. 

PAGEDEF.  Page  definition 

parallel  device.  A  device  that  can  perform  two 
or  more  concurrent  activities.  Contrast  with 
Serial  Device. 

parameter.  (1)  Information  that  the  user 
supplies  to  a  panel,  command,  or  function.  (2) 
In  the  AIX  operating  system,  a  keyword-value 
pair. 
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partitioned  data  set.  A  data  set  in  direct 
access  storage  that  is  divided  into  partitions, 
called  members,  each  of  which  can  contain  a 
program,  part  of  a  program,  or  data. 

path.  In  a  network,  any  route  between  any  two 
nodes. 

path  name.  A  name  that  specifies  the  location 
of  a  directory  within  a  file  system.  Path  names 
are  used  to  locate  and  reference  directories 
and  their  contents. 

PC.  Personal  Computer 

PCL.  Printer  control  language 

PCX.  Picture  Exchange  Format 

PDF.  Portable  Document  Format 

permissions.  Codes  that  determine  the  users 
that  can  access  a  system,  that  determine  how 
data  can  be  used  by  any  users  who  can 
access  the  system,  and  that  determine  other 
types  of  tasks  users  of  the  system  can 
perform. 

personal  computer.  A  microcomputer 
primarily  intended  for  stand-alone  use  by  an 
individual.  (T) 

Picture  Exchange  Format  (PCX).  A  file  that 
contains  a  graphic  in  the  PCX  graphics  file 
format,  which  was  originally  developed  for  the 
PC  Paintbrush  program,  but  is  now  widely 
used  by  other  programs. 

piobe.  The  printer  input/output  back  end 
program  used  by  AIX  for  printing  tasks. 


pipe.  To  direct  the  data  so  that  the  output  from 
one  process  becomes  the  input  to  another 
process.  The  standard  output  of  one 
command  can  be  connected  to  the  standard 
input  of  another  with  the  pipe  operator  (I).  Two 
commands  connected  in  this  way  constitute  a 
pipeline. 

point.  (1)  To  move  the  mouse  pointer  to  a 
specific  object.  (2)  A  unit  of  typesetting 
measure  equal  to  0.01384  inch  (0.35054  mm), 
or  about  1/72  of  an  inch.  There  are  12  points 
per  pica. 

point  size.  The  height  of  a  font  in  points.  See 
also  Point. 

policy  domain.  In  TSM,  a  policy  object  that 
contains  policy  sets,  management  classes, 
and  copy  groups  that  is  used  by  a  group  of 
client  nodes.  See  Policy  Set,  Management 
Class,  Copy  Group,  and  Client  Node. 

policy  set.  In  TSM,  a  policy  object  that 
contains  a  group  of  management  class 
definitions  that  exist  for  a  policy  domain.  At 
any  one  time,  there  can  be  many  policy  sets 
within  a  policy  domain  but  only  one  policy  set 
can  be  active.  See  Management  Class  and 
Active  Policy  Set. 

port.  (1)  A  part  of  the  system  unit  or  remote 
controller  to  which  cables  for  external  devices 
(display  stations,  terminals,  or  printers)  are 
attached.  The  port  is  an  access  point  for  data 
entry  or  exit.  (2)  A  specific  communications 
end  point  within  a  host.  A  port  is  identified  by  a 
port  number. 
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Portable  Document  Format.  A  distilled 
version  of  PostScript  data  that  adds  structure 
and  efficiency.  PDF  data  has  the  same 
imaging  model  as  PostScript  but  does  not 
have  its  programmability.  PDF  also  provides 
direct  access  to  pages  and  allows  hypertext 
links,  bookmarks,  and  other  navigational  aids 
required  for  viewing.  The  text  in  a  PDF  file  is 
usually  compressed  using  LZW  methods.  The 
images  is  a  PDF  file  are  usually  compressed 
using  CCITT  or  JPEG  methods. 

PostScript.  Adobe’s  page  description 
language  used  for  printing.  PostScript  is  a  very 
flexible  programming  language  and  imaging 
model  but  is  not  as  structured  as  AFP. 
PostScript  cannot  be  parsed  to  determine 
page  boundaries,  it  must  be  interpreted. 
Because  of  this  limitation,  PostScript  is  not 
practical  for  archiving  and  viewing.  Adobe 
created  PDF  for  archiving  and  viewing. 

press.  To  touch  a  specific  key  on  the 
keyboard. 

primary  log  file.  A  set  of  one  or  more  log  files 
used  to  record  changes  to  a  database. 

Storage  for  these  files  is  allocated  in  advance. 

primary  storage  pool.  A  named  collection  of 
storage  volumes  in  which  TSM  stores  archive 
copies  of  files. 

print  file.  (1)  The  output  of  a  user-defined 
program  that  is  to  be  indexed  and  loaded  into 
the  system.  (2)  A  file  that  a  user  wants  to  print. 

print  job.  A  series  of  print  files  scheduled  for 
printing.  At  print  submission  time,  the  user  can 
request  one  or  more  files  to  be  printed; 
therefore,  a  print  job  consists  of  one  or  more 
print  files. 

print  queue.  A  file  containing  a  list  of  the 
names  of  files  waiting  to  be  printed. 


Print  Services  Facility  (PSF).  A  sophisticated 
IBM  print  subsystem  that  drives  IPDS  page 
printers.  PSF  is  supported  under  MVS,  VSE, 
VM,  OS/2,  AIX,  and  is  a  standard  part  of  the 
operating  system  under  OS/400.  PSF 
manages  printer  resources  such  as  fonts, 
images,  electronic  forms,  form  definitions,  and 
page  definitions,  and  provides  error  recovery 
for  print  jobs. 

When  printing  line  data,  PSF  supports  external 
formatting  using  page  definitions  and  form 
definitions.  This  external  formatting  extends 
page  printer  functions  such  as  electronic  forms 
and  use  of  typographic  fonts  without  any 
change  to  applications  that  generate  the  data. 

Print  Services  Facility/2  (PSF/2).  PSF/2  is  an 
OS/2-based  print  server  that  drives  IPDS  page 
printers,  as  well  as  IBM  PPDS  and  FIP-PCL 
compatible  printers.  PSF/2  manages  printer 
resources  and  provides  error  recovery  for  print 
jobs.  PSF/2  supports  distributed  printing  of 
AFP  print  jobs  from  PSF  for  AIX,  PSF/MVS, 
PSF/VSE,  PSF/VM,  and  OS/400.  PSF/2  also 
supports  printing  from  a  wide  range  of 
workstation  applications,  including  Microsoft 
Windows  and  OS/2  Presentation  Manager,  as 
well  as  the  ASCII,  PostScript,  and  AFP  data 
streams. 

Print  Services  Facility  for  AIX  (PSF  for  AIX). 

An  IBM  licensed  program  that  produces  printer 
commands  from  the  data  sent  to  it  and  it  runs 
on  the  AIX/6000  ©operating  system. 

print  spooler.  The  print  spooler  directs  the 
printing  of  data  from  different  applications.  It 
temporarily  stores  information  in  separate  files 
until  they  are  printed. 

Printer  Control  Language  (PCL).  The  data 
stream  used  by  Hewlett-Packard  LaserJet  II 
and  III  and  other  compatible  printers. 
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process.  An  activity  within  the  system  that  is 
started,  such  as  a  command,  a  shell  program, 
or  another  process. 

profile.  (1)  A  file  containing  customized 
settings  for  a  system  or  user.  (2)  Data 
describing  the  significant  features  of  a  user, 
program,  or  device. 

program  level.  The  version,  release, 
modification,  and  fix  levels  of  a  program. 

prompt.  A  displayed  symbol  or  message  that 
requests  information  or  operator  action. 

protocol.  A  set  of  semantic  and  syntactic 
rules  that  determines  the  behavior  of 
functional  units  in  achieving  communication. 

PSF.  Print  Services  Facility 

PSF/2.  Print  Services  Facility/2 

PSF  for  AIX.  Print  Services  Facility  for  AIX 

PTF.  Program  temporary  fix 

Q 

qdaemon.  The  daemon  process  that 
maintains  a  list  of  outstanding  jobs  and  sends 
them  to  the  specified  device  at  the  appropriate 
time. 

qualified  name.  (1)  A  data  name  explicitly 
accompanied  by  a  specification  of  the  class  to 
which  it  belongs  in  a  specified  classification 
system.  (I)  (A)  (2)  A  name  that  has  been  made 
unique  by  the  addition  of  one  or  more 
qualifiers. 

queue.  (1)  A  line  or  list  formed  by  items 
waiting  to  be  processed.  (2)  To  form  or 
arrange  in  a  queue. 


queue  device.  A  logical  device  defining 
characteristics  of  a  physical  device  attached  to 
a  queue. 

R 

radio  button.  Round  option  buttons  grouped 
in  dialog  boxes;  one  is  preselected.  Like  a 
radio  in  an  automobile,  select  only  one  button 
(“station”)  at  a  time. 

RAM.  Random  access  memory.  Specifically, 
the  memory  used  for  system  memory. 
Sometimes  this  memory  is  referred  to  as  main 
storage. 

raster.  In  Advanced  Function  Presentation,  an 
on/off  pattern  of  electrostatic  images  produced 
by  the  laser  print  head  under  control  of  the 
character  generator. 

raster  font.  A  font  in  which  the  characters  are 
defined  directly  by  the  raster  bit  map.  See 
Font.  Contrast  with  Outline  Font. 

raster  graphics.  Computer  graphics  in  which 
a  display  image  is  composed  of  an  array  of 
pixels  arranged  in  rows  and  columns. 

read  access.  In  computer  security, 
permission  to  read  information. 

record.  (1)  In  programming  languages,  an 
aggregate  that  consists  of  data  objects, 
possibly  with  different  attributes,  that  usually 
have  identifiers  attached  to  them.  (2)  A  set  of 
data  treated  as  a  unit.  (3)  A  collection  of  fields 
treated  as  a  unit. 

recovery  log.  In  TSM,  a  log  of  updates  that 
are  about  to  be  written  to  the  database.  The 
log  can  be  used  to  recover  from  system  and 
media  failures. 
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recovery  procedure.  (1)  An  action  performed 
by  the  operator  when  an  error  message 
appears  on  the  display  screen.  This  action 
usually  permits  the  program  to  run  the  next 
job.  (2)  The  method  of  returning  the  system  to 
the  point  where  a  major  system  error  occurred 
and  running  the  recent  critical  jobs  again. 

register.  To  define  a  client  node  to  TSM. 

remote.  Pertaining  to  a  system  or  device  that 
is  accessed  through  a  communications  line. 
Contrast  with  Local. 

remote  print.  Issuing  print  jobs  to  one 
machine  (client)  to  print  on  another  machine 
(server)  on  a  network. 

remote  system.  A  system  that  is  connected  to 
your  system  through  a  communication  line. 

report.  A  print  data  stream  produced  by  a 
user-defined  program  or  other  software 
program  that  can  contains  hundreds  or 
thousands  of  pages  of  related  information. 
Most  reports  can  be  logically  divided  and 
indexed  into  single  and  multiple  page  objects 
called  documents. 

resolution.  (1)  In  computer  graphics,  a 
measure  of  the  sharpness  of  an  image, 
expressed  as  the  number  of  lines  and  columns 
on  the  display  screen.  (2)  The  number  of  pels 
per  unit  of  linear  measure. 

resource.  A  collection  of  printing  instructions, 
and  sometimes  data  to  be  printed,  that 
consists  entirely  of  structured  fields.  A 
resource  can  be  stored  as  a  member  of  a 
directory  and  can  be  called  for  by  the  Print 
Services  Facility  when  needed.  The  different 
resources  are:  coded  font,  character  set,  code 
page,  page  segment,  overlay,  and  form 
definition. 


resource  directory.  A  place  in  which 
resource  files  are  stored. 

resource  management.  The  function  that 
protects  serially  accessed  resources  from 
concurrent  access  by  computing  tasks. 

retention.  The  amount  of  time,  in  days,  that 
archived  files  will  be  retained  in  TSM  before 
they  are  deleted. 

retry.  To  try  the  operation  that  caused  the 
device  error  message  again. 

return  code.  (1)  A  value  that  is  returned  to  a 
program  to  indicate  the  results  of  an  operation 
issued  by  that  program.  (2)  A  code  used  to 
influence  the  running  of  succeeding 
instructions. 

root.  On  UNIX  servers,  the  user  name  for  the 
system  user  with  the  most  authority. 

root  file  system.  In  UNIX  environments,  the 
file  system  that  contains  all  of  the  default 
installation  and  program  directories  in  the 
system. 

root  user.  In  UNIX  environments,  an  expert 
user  who  can  log  in  and  execute  restricted 
commands,  shut  down  the  system,  and  edit  or 
delete  protected  files. 

root  volume  group.  In  UNIX  environments, 
the  volume  group,  identified  with  a  single  / 
(forward  slash)  that  contains  all  the  directories 
in  the  root  file  system. 
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rotation.  (1)  The  alignment  of  a  character  with 
respect  to  its  character  baseline,  measured  in 
degrees  in  a  clockwise  rotation.  Examples  are 
0°,  90°,  180°,  and  270°.  Zero-degree 
character  rotation  exists  when  a  character  is  in 
its  customary  alignment  with  the  baseline. 
Synonymous  with  Character  Rotation.  (2)  The 
number  of  degrees  a  character  is  turned 
relative  to  the  page  coordinates.  (3)  The 
orientation  of  the  characters  of  a  font  with 
respect  to  the  baseline. 

routing.  The  assignment  of  the  path  by  which 
a  message  will  reach  its  destination. 

S 

secondary  log  file.  A  set  of  one  or  more  log 
files  used  to  record  changes  to  a  database. 
Storage  for  these  files  is  allocated  as  needed 
when  the  primary  log  fills  up. 

segment.  (1)  A  collection  of  composed  text 
and  images,  prepared  before  formatting  and 
included  in  a  document  when  it  is  printed.  See 
Page  Segment.  (2)  The  resource  that  contains 
the  structured-field  definition  of  a  page 
segment.  (3)  A  100  page  portion  of  a  report 
file.  OnDemand  divides  report  files  into 
segments  to  provide  enhanced  performance 
and  maintenance. 

segment  table.  A  high-level  index  to  index 
data  stored  in  an  application  group.  Each  row 
in  the  segment  table  identifies  a  table  of 
application  group  index  data.  OnDemand  uses 
the  segment  table  to  limit  a  query  to  a  specific 
table  of  application  group  index  data. 

select.  To  pick  a  menu  command  or  other 
object  with  a  single  click  of  the  mouse. 


serial  device.  A  device  that  performs 
functions  sequentially,  such  as  a  serial  printer 
that  prints  one  byte  at  a  time.  Contrast  with 
Parallel  Device. 

server.  (1)  On  a  network,  the  computer  that 
contains  the  data  or  provides  the  facilities  to 
be  accessed  by  other  computers  on  the 
network.  (2)  A  program  that  handles  protocol, 
queuing,  routing,  and  other  tasks  necessary 
for  data  transfer  between  devices  in  a 
computer  system.  (3)  A  workstation  connected 
to  a  TCP/IP  network  that  runs  the  OnDemand 
programs  that  store,  retrieve,  and  maintain 
report  files.  OnDemand  supports  two  types  of 
servers:  a  library  server  an  object  server. 

server  options  file.  The  TSM  file  that 
specifies  processing  options  for 
communication  methods,  tape  handling,  pool 
sizes,  language,  and  date,  time,  and  number 
formats. 

shell.  In  UNIX  environments,  a  software 
interface  between  a  user  and  the  operating 
system  of  a  computer.  Shell  programs 
interpret  commands  and  user  interactions  on 
devices  such  as  keyboards  and  pointing 
devices  and  communicate  them  to  the 
operating  system. 

skip-to-channel  control.  A  line  printer  control 
appearing  in  line  data.  Allows  space  to  be  left 
between  print  lines.  Compatible  with  page 
printers  when  the  data  is  formatted  by  page 
definitions. 

SMIT.  System  Management  Interface  Tool 

SMS.  System  Managed  Space 

software.  Programs,  procedures,  rules,  and 
any  associated  documentation  pertaining  to 
the  operating  of  a  system.  Contrast  with 
Hardware. 
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spool  file.  (1 )  A  disk  file  containing  output  that 
has  been  saved  for  later  printing.  (2)  Files 
used  in  the  transmission  of  data  among 
devices,  spooling  (simultaneous  peripheral 
operation 

online).  Performing  a  peripheral  operation 
such  as  printing  while  the  computer  is  busy 
with  other  work. 

spooling  subsystem.  A  synonym  for  the 
queuing  system  that  pertains  to  its  use  for 
queuing  print  jobs. 

stand-alone  workstation.  A  workstation  that 
can  perform  tasks  without  being  connected  to 
other  resources  such  as  servers  or  host 
systems. 

standard  input.  The  primary  source  of  data 
going  into  a  command.  Standard  input  comes 
from  the  keyboard  unless  redirection  or  piping 
is  used,  in  which  case  standard  input  can  be 
from  a  file  or  the  output  from  another 
command. 

standard  output.  The  primary  destination  of 
data  coming  from  a  command.  Standard 
output  goes  to  the  display  unless  redirection  or 
piping  is  used,  in  which  case  standard  output 
can  be  to  a  file  or  another  command. 

status.  (1 )  The  current  condition  or  state  of  a 
program  or  device.  For  example,  the  status  of 
a  printer.  (2)  The  condition  of  the  hardware  or 
software,  usually  represented  in  a  status  code. 

storage.  (1)  The  location  of  saved  information. 
(2)  In  contrast  to  memory,  the  saving  of 
information  on  physical  devices  such  as  disk 
or  tape. 

storage  device.  A  functional  unit  for  storing 
and  retrieving  data. 


storage  hierarchy.  A  logical  ordering  of 
storage  devices.  Generally,  the  ordering  is 
based  on  the  speed  and  capacity  of  the 
devices. 

storage  node.  A  named  object  that  identifies 
the  locations  used  to  hold  report  data.  A 
storage  node  can  identify  cache  storage  and  a 
TSM  domain  on  an  OnDemand  object  server. 

storage  object.  A  portion  of  a  storage  volume 
managed  as  a  single  entity.  A  storage  object 
can  contain  many  segments  of  report  data. 

storage  pool.  In  TSM,  a  named  collection  of 
storage  volumes  that  is  the  destination  for 
archived  files. 

storage  pool  volume.  In  TSM,  a  volume  that 
has  been  assigned  to  a  storage  pool  to  store 
archived  files. 

storage  set.  A  named  collection  of  storage 
nodes  that  determines  the  locations  that  can 
hold  report  data. 

storage  volume.  A  volume  that  has  been 
assigned  to  hold  report  data  on  an  OnDemand 
server. 

string.  A  series  or  set  of  alphabetic  or  numeric 
characters.  A  string  can  be  composed  of 
letters,  numbers,  and  special  characters. 

structure.  A  variable  that  contains  an  ordered 
group  of  data  objects.  Unlike  an  array,  the 
data  objects  within  a  structure  can  have  varied 
data  types. 
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structured  field.  (1)  A  self-identifying, 
variable-length,  bounded  record  that  can  have 
a  content  portion  that  provides  control 
information,  data,  or  both.  (2)  A  mechanism 
that  permits  variable  length  data  to  be 
encoded  for  transmission  in  the  data  stream. 
See  Field. 

subdirectory.  In  the  file  system  hierarchy,  a 
directory  contained  within  another  directory. 

subroutine.  (1)  A  sequenced  set  of 
statements  or  coded  instructions  that  can  be 
used  in  one  or  more  computer  programs  and 
at  one  or  more  points  in  a  computer  program. 
(2)  A  routine  that  can  be  part  of  another 
routine. 

syntax.  The  grammatical  rules  for 
constructing  a  command,  statement,  or 
program. 

syntax  diagram.  A  diagram  for  a  command 
that  displays  how  to  enter  the  command  on  the 
command  line. 

system  console.  A  console,  usually  equipped 
with  a  keyboard  and  display  screen,  that  is 
used  by  an  operator  to  control  and 
communicate  with  a  system.  Synonymous 
with  Console. 

system  customization.  Specifying  the 
devices,  programs,  and  users  for  a  particular 
data  processing  system.  See  also 
Configuration. 

system  integrity.  In  computer  security,  the 
quality  of  a  system  that  can  perform  its 
intended  function  in  an  unimpaired  manner, 
free  from  deliberate  or  inadvertent 
unauthorized  manipulation  of  the  system. 


System  Managed  Space  (SMS).  A  type  of 
DB2  table  space.  An  SMS  table  space  is 
managed  by  the  filesystem  manager. 

system  management.  The  tasks  involved  in 
maintaining  the  system  in  good  working  order 
and  modifying  the  system  to  meet  changing 
requirements. 

System  Management  Interface  Tool  (SMIT). 

In  the  AIX  operating  system,  a  series  of  panels 
that  allow  you  to  perform  system  functions 
without  directly  issuing  any  commands. 

system  memory.  Synonymous  with  Main 
Storage,  but  used  in  hardware  to  refer  to 
semiconductor  memory  (modules). 

system  prompt.  Synonym  for  command  line. 
The  system  prompt  is  the  symbol  that  appears 
at  the  command  line  of  an  operating  system. 
The  system  prompt  indicates  that  the 
operating  system  is  ready  for  the  user  to  enter 
a  command. 

T 

table.  A  named  collection  of  data  consisting  of 
rows  and  columns. 

table  reference  character  (TRC).  (1)  Usually, 
the  second  byte  on  a  line  in  the  user’s  data. 
This  byte  contains  a  value  (0-1 26)  that  is  used 
to  select  a  font  to  be  used  to  print  that  line.  (2) 
In  the  3800  Printing  Subsystem,  a  numeric 
character  (0,  1,  2,  or  3)  corresponding  to  the 
order  in  which  the  character  arrangement 
table  names  have  been  specified  with  the 
CHARS  keyword.  It  is  used  for  selection  of  a 
character  arrangement  table  during  printing. 
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table  space.  An  abstraction  of  a  collection  of 
containers  into  which  database  objects  are 
stored.  A  table  space  provides  a  level  of 
indirection  between  a  database  and  the  tables 
stored  within  the  database.  A  table  space  has 
space  on  media  storage  devices  assigned  to  it 
and  has  tables  created  within  it. 

tag.  (1)  A  type  of  structured  field  used  for 
indexing  in  an  AFP  document.  Tags  associate 
an  index  attribute-value  pair  with  a  specific 
page  or  group  of  pages  in  a  document.  (2)  In 
text  formatting  markup  language,  a  name  for  a 
type  of  document  element  that  is  entered  in 
the  source  document  to  identify  it. 

Tagged  Image  File  Format  (TIFF).  A 

bit-mapped  graphics  format  for  scanned 
images  with  resolutions  of  up  to  300  dpi.  TIFF 
simulates  gray  scale  shading. 

TB.  Terabyte 

TCP.  Transmission  Control  Protocol 

TCP/IP.  Transmission  Control 
Protocol/Internet  Protocol 

terabyte.  A  unit  of  memory  or  space 
measurement  capacity  equal  to  approximately 
one  trillion  bytes.  One  terabyte  is  equal  to 
1,000  gigabytes,  or  one  million  megabytes. 

text.  (1)  A  type  of  data  consisting  of  a  set  of 
linguistic  characters  (letters,  numbers,  and 
symbols)  and  formatting  controls.  (2)  In  word 
processing,  information  intended  for  human 
viewing  that  is  presented  in  a  two-dimensional 
form,  such  as  data  printed  on  paper  or 
displayed  on  a  screen. 

throughput.  A  measure  of  the  amount  of  work 
performed  by  a  computer  system  over  a 
period  of  time,  for  example,  the  number  of  jobs 
per  day.  (I) 


TIFF.  Tagged  Image  File  Format 

Tivoli  Storage  Manager.  An  IBM  software 
program  that  provides  archive  storage 
management  of  data  stored  in  an  OnDemand 
system. 

token  name.  An  eight-byte  name  that  can  be 
given  to  all  data  stream  objects. 

token-ring  network.  A  ring  network  that 
allows  unidirectional  data  transmission 
between  data  stations,  by  a  token  passing 
procedure,  such  that  the  transmitted  data 
return  to  the  transmitting  station.  (T) 

toolbar.  The  region  directly  beneath  the  menu 
bar  of  the  main  window  in  OnDemand  client 
programs  that  support  a  graphical  user 
interface. 

toolbar  button.  A  small  bitmap  on  the  toolbar 
that  represents  a  command  in  OnDemand 
client  programs  that  support  a  graphical  user 
interface.  Click  a  toolbar  button  to  quickly 
access  a  command. 

transfer.  To  send  data  to  one  place  and  to 
receive  data  at  another  place. 

transform.  To  change  the  form  of  data 
according  to  specified  rules  without 
significantly  changing  the  meaning  of  the  data. 
(I)  (A) 

Transmission  Control  Protocol  (TCP).  A 

communications  protocol  used  in  Internet  and 
in  any  network  that  follows  the  U.S. 
Department  of  Defense  standards  for 
inter-network  protocol.  TCP  provides  a 
host-to-host  protocol  between  hosts  in 
packet-switched  communications  networks 
and  in  interconnected  systems  of  such 
networks.  It  assumes  that  the  Internet  protocol 
is  the  underlying  protocol. 
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Transmission  Control  Protocol/Internet 
Protocol  (TCP/IP).  A  set  of  communications 
protocols  that  support  peer-to-peer 
connectivity  functions  for  both  local  and  wide 
area  networks. 

TRC.  Table  reference  character 

trigger.  Data  values  that  ACIF  searches  for  in 
the  input  data  stream,  to  delineate  the 
beginning  of  a  new  group  of  pages.  The  first 
trigger  is  then  the  anchor  point  that  ACIF  uses 
to  locate  index  values. 

TSM.  Tivoli  Storage  Manager 

type.  To  enter  specific  information  using  the 
keyboard,  typing  characters  exactly  as  given. 

U 

unformatted  print  data.  Data  that  is  not 
formatted  for  printing.  A  page  definition  can 
contain  controls  that  map  unformatted  print 
data  to  its  output  format. 

UNIX  operating  system.  An  operating  system 
developed  by  Bell  Laboratories  that  features 
multiprogramming  in  a  multi-user  environment. 
The  UNIX  operating  system  was  originally 
developed  for  use  on  minicomputers  but  has 
been  adapted  for  mainframes  and 
microcomputers. 

upload.  To  transfer  data  from  one  computer  to 
another.  Typically,  users  upload  from  a  small 
computer  to  a  large  one. 

user.  A  person  authorized  to  logon  to  an 
OnDemand  server. 


user  exit.  (1)  A  point  in  an  IBM-supplied 
program  at  which  a  user-defined  program  may 
be  given  control.  (2)  A  programming  service 
provided  by  an  IBM  software  product  that  may 
be  requested  during  the  execution  of  an 
application  program  for  the  service  of 
transferring  control  back  to  the  application 
program  upon  the  later  occurrence  of  a 
user-specified  event. 

user  interface.  The  hardware,  software,  or 
both  that  implements  a  user  interface,  allowing 
the  user  to  interact  with  and  perform 
operations  on  a  system,  program,  or  device. 
Examples  are  a  keyboard,  mouse,  command 
language,  or  windowing  subsystem. 

V 

value.  (1)  A  set  of  characters  or  a  quantity 
associated  with  a  parameter  or  name.  (2)  A 
quantity  assigned  to  a  constant,  variable, 
parameter,  or  symbol. 

variable.  (1)  A  name  used  to  represent  a  data 
item  whose  value  can  change  while  the 
program  is  running.  (2)  In  programming 
languages,  a  language  object  that  can  take 
different  values  at  different  times.  (3)  A 
quantity  that  can  assume  any  of  a  given  set  of 
values. 

version  number.  The  version  level  of  a 
program,  which  is  an  indicator  of  the  hardware 
and  basic  operating  system  upon  which  the 
program  operates.  The  version,  release, 
modification,  and  fix  levels  together  comprise 
the  program  level  or  version  of  a  program. 


Glossary  313 


virtual  printer.  A  view  of  a  printer  that  refers 
only  to  the  high-level  data  stream,  such  as 
ASCII  or  PostScript,  that  the  printer 
understands.  It  does  not  include  any 
information  about  how  the  printer  hardware  is 
attached  to  the  host  computer  or  the  protocol 
used  for  transferring  data  to  and  from  the 
printer. 

volume.  The  basic  unit  of  storage  for  a 
database,  log  file,  or  a  storage  pool.  A  volume 
can  be  an  LVM  logical  volume,  a  standard  file 
system  file,  a  tape  cartridge,  or  an  optical 
platter.  Each  volume  is  identified  by  a  unique 
volume  identifier. 

W 

wildcard.  Search  characters  that  represent 
other  letters,  numbers,  or  special  characters. 
In  OnDemand,  the  %(percentage)  and  the 
_(underscore)  are  wildcard  characters. 

window.  A  part  of  a  display  screen  with  visible 
boundaries  in  which  information  is  presented. 

workstation.  A  terminal  or  microcomputer, 
usually  one  that  is  connected  to  a  mainframe 
or  to  a  network,  at  which  a  user  can  perform 
applications. 

write  access.  In  computer  security, 
permission  to  write  to  an  object. 

writer.  A  JES  function  that  processes  print 
output. 
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Related  publications 


The  publications  listed  in  this  section  are  considered  particularly  suitable  for  a 
more  detailed  discussion  of  the  topics  covered  in  this  redbook. 


IBM  Redbooks 

For  information  on  ordering  these  publications,  see  “How  to  get  IBM  Redbooks” 

on  page  317. 

►  UNIX  System  Services  Command  Reference,  SC28-1 892 

►  OS/390  UNIX  System  Services  Implementation  and  Customization, 
SG24-5178 

Other  resources 

These  publications  are  also  relevant  as  further  information  sources: 

►  IBM  Content  Manager  OnDemand  -  User’s  Guide,  SC27-0836 

►  IBM  Content  Manager  OnDemand  -  Windows  Client  Customization  Guide 
and  Reference,  SC27-0837 

►  IBM  Content  Manager  OnDemand  -  Messages  and  Codes,  SC27-1 379 

►  IBM  Content  Manager  OnDemand  for  Multiplatforms  -  Administrator’s  Guide, 
SC27-0840 

►  IBM  Content  Manager  OnDemand  for  Multiplatforms  -  Indexing  Reference, 
SC27-0842 

►  IBM  Content  Manager  OnDemand  for  Multiplatforms  -  Installation  and 
Configuration  Guide  for  UNIX  Servers,  GC27-0834 

►  IBM  Content  Manager  OnDemand  for  Multiplatforms  -  Installation  and 
Configuration  Guide  for  Windows  Servers,  GC27-0835 

►  IBM  Content  Manager  OnDemand  for  Multiplatforms  -  Introduction  and 
Planning  Guide,  GC27-0839 

►  IBM  Content  Manager  OnDemand  -  Web  Enablement  Kit  Installation  and 
Configuration  Guide,  SC27-1000 

►  IBM  Content  Manager  OnDemand  forz/OS  and  OS/390  -  Configuration 
Guide,  GC27-1373 
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►  IBM  Content  Manager  OnDemand  for  z/OS  and  OS/390  -  Administration 
Guide,  SC27-1 374 

►  IBM  Content  Manager  OnDemand  for  z/OS  and  OS/390  -  Indexing 
Reference,  SC27-1375 

►  IBM  Content  Manager  OnDemand  for  z/OS  and  OS/390  -  Web  Enablement 
Kit  Installation  and  Configuration  Guide,  SC27-1376 

►  IBM  Content  Manager  OnDemand  for  z/OS  and  OS/390  -  OnDemand 
Distribution  Facility  Installation  Guide  and  Reference,  SC27-1377 

►  IBM  Content  Manager  OnDemand  for  z/OS  and  OS/390  -  Introduction  and 
Planning  Guide,  GC27-1438 

►  IBM  Content  Manager  OnDemand  for  iSeries  -  Administration  Guide, 
SC41-5325 

►  IBM  Content  Manager  OnDemand  for  iSeries  -  Installation  Guide,  SC41  -5333 

►  IBM  Content  Manager  OnDemand  for  iSeries  Common  Server  - 
Administration  Guide,  SC27-1 161 

►  IBM  Content  Manager  OnDemand  for  iSeries  Common  Server  -  Server 
Planning  and  Installation  Guide,  SC27-1 1 58 

►  IBM  Content  Manager  OnDemand  for  iSeries  Common  Server  -  Indexing 
Reference,  SC27-1 1 60 

►  IBM  Content  Manager  OnDemand  for  iSeries  Common  Server  -  Web 
Enablement  Kit  Installation  and  Configuration  Guide,  SC27-1 1 63 

►  IBM  Content  Manager  OnDemand  for  Multiplatforms  Release  Notes  for 
Version  7.1.0.10 

►  IBM  DB2  UDB  for  z/OS  and  OS/390  -  Administration  Guide,  SC26-9931 

►  Tivoli  Storage  Manager  for  Windows  Administrator’s  Guide,  GC32-0782 

►  Tivoli  Storage  Manager  forAlX  Administrator’s  Guide,  GC32-0768 

►  Tivoli  Storage  Manager  for  Windows  Quick  Start,  GC32-0784 

►  z/OS  MVS  Initialization  and  Tuning  Reference,  SA22-7592 

►  z/OS  MVS  System  Commands,  SA22-7627 

►  DFSMS  Object  Access  Method  Planning,  Installation,  and  Storage 
Administration  Guide  for  Object  Support,  SC35-0426 

►  OS/390  OpenEdit  Command  Reference,  SC28-1 982 

►  PDF  Reference,  third  edition,  Adobe  Potable  Document  Format  Version  1.4, 
Addison-Wesley,  2001,  ISBN  0-201-75839-3 

►  Adobe  Type  1  Font  Format,  Addison-Wesley  1990,  ISBN  0-201-57044-0 

►  Xenos  d2e  Platform  User  Guide 
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►  Xenos  d2e  Platform  Scripting  Reference 

►  Xenos  d2e  Developer  Studio  User  Guide 

Referenced  Web  sites 

These  Web  sites  are  also  relevant  as  further  information  sources: 

►  OnDemand  production  information: 

http://www. ibm.com/software/data/ondemand/ 

►  z/OS  information 

http://www. ibm.com/servers/eserver/zseries/zos 

►  OS/390  information 
http://www.ibm.com/servers/s390/os390 

►  DB2  UDB  for  z/OS  and  OS/390  information 
http://www. ibm.eom/software/db2zos/l i brary.html 

►  iSeries  Information  Center 

http://www. ibm.com/eserver/i series/infocenter 

►  iSeries  Navigator  information 

http://www. ibm.com/eserver/i seri es/navi gator/ 

►  IBM  Printing  Systems  Division  Web  site  for  Infoprint  product  information 
http://www.printers.ibm.com 

►  Tivoli  Storage  Manager  home  page  for  TSM  information 

http://www.tivoli .com/tsm 


How  to  get  IBM  Redbooks 

You  can  order  hardcopy  Redbooks,  as  well  as  view,  download,  or  search  for 
Redbooks  at  the  following  Web  site: 

ibm.com/redbooks 

You  can  also  download  additional  materials  (code  samples  or  diskette/CD-ROM 
images)  from  that  site. 
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IBM  Redbooks  collections 


Redbooks  are  also  available  on  CD-ROMs.  Click  the  CD-ROMs  button  on  the 
Redbooks  Web  site  for  information  about  all  the  CD-ROMs  offered,  as  well  as 
updates  and  formats. 
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